# Troubleshooting

Start with the symptom below. Check current state before retrying any action that may have changed files, accounts, or external services.

## Quick answers

| Symptom | First check | Next step |
|---|---|---|
| Sending opens Settings | The selected preset is not ready | Configure its provider, model, and sign-in |
| Syntheo cannot find a file | The wrong workspace may be selected | Select the correct workspace and mention the file with `@` |
| A task appears stuck | It may be waiting for you | Open the task and look for a question or approval |
| A request is too large | The thread has too much context | Compress it or start a new thread |
| Changes are in an unexpected place | The task may use a Virtual Edit or room | Check the active location shown by the task |
| File Diff is empty | The change may have come from another app or command | Check the full Git change list |
| Room tasks exist but are not running | Creating and starting are separate | Start the intended tasks |
| A schedule did not run | Syntheo may have been closed or asleep | Use Run now and check time, timezone, and enabled state |
| A connected tool is missing | It may need refresh or explicit selection | Refresh it or select it with `@` |
| A phone will not pair | Network or pairing details may be stale | Create a new code and try manual pairing |

## Provider and model problems

### Sending opens AI Provider settings

1. Open **Settings → AI Provider**.
2. Find the preset you selected.
3. Choose an available provider and model.
4. Sign in or save the required key.
5. Test with a small Ask task.

If the model is shown as unavailable, choose another model offered to the connected account.

### Sign-in fails

- Confirm that the account belongs to the selected provider.
- Confirm that the account has access to the selected model.
- Use OpenAI Codex for eligible ChatGPT subscription access rather than the regular API-key connection.
- Disconnect and sign in again if you changed accounts.
- Never paste account secrets into a task for diagnosis.

## Workspace and file problems

### Syntheo is using the wrong project

Stop the task, then:

1. Check the workspace shown near the composer.
2. Check whether the task uses a Virtual Edit or a room.
3. Review any files already changed.
4. Start a new thread in the correct workspace.

Do not erase changes you have not identified.

### A file does not appear in `@` search

- Confirm the selected workspace.
- Type more of the file's path.
- Check whether the file is outside the workspace.
- Add the correct project folder as a workspace when needed.

### Code Atlas results look old

Open **Settings → Workspace → Code Intelligence** and choose **Sync index** for the current workspace.

## Task and approval problems

### The task is waiting

Look for a permission request, structured question, or “needs input” indicator. Answer it or deny the request with a safe alternative.

### The task is going in the wrong direction

Send one short correction with the new evidence or priority. If the objective or workspace is wrong, stop and restart with a clean prompt.

### The request is too large

Compress the thread when the goal is unchanged. Start a new thread when the goal changed. Keep only the current outcome, decisions, useful evidence, and remaining check.

### A task failed or stopped

Read its latest status and summary. A failed final response does not prove earlier actions were undone. Inspect changed files and external state before trying again.

## Change and review problems

### File Diff does not show everything

File Diff may not include changes made by another app or by some commands. Use your normal Git view to inspect all current and staged changes.

### A Virtual Edit will not apply

The main workspace and Virtual Edit may contain conflicting changes. Preserve both, read the reported conflict, and choose a deliberate resolution. Do not delete the layer or reset the project before its unique work is safe.

### A commit includes the wrong files

Stop before pushing. Review the staged and committed file list, preserve unrelated work, and follow your normal team policy for correcting the commit.

### Pull or Sync is refused

Local and remote work may have diverged. Review both sides before choosing how to combine them. Do not force or rewrite shared history without clear authorization.

## Autonomy and connected-tool problems

### A room task exists but is not running

Open its menu and choose Run, or tell Conductor to start the specific tasks it created.

### Two tasks are changing the same area

Stop at least one task. Give each task separate ownership and name one integration owner before resuming.

### A Skill or connected tool is not available

- Confirm it is enabled.
- Refresh connected tools.
- If it is User invoked, select it with `@` in the same prompt.
- Check **Settings → Permissions** for the tool's approval mode.

## Schedule and mobile problems

### A schedule is overdue

Confirm that Syntheo was open, the computer was awake, the schedule was enabled, the time and timezone are correct, and provider access was available. Use **Run now** to test it.

### Local phone pairing fails

- Put phone and desktop on the same reachable network.
- Create a **New code**.
- Try the manual address and code.
- Temporarily check whether a VPN or firewall is isolating the devices.

### Remote mobile access fails

Confirm that the relay address is correct and trusted, both devices are online, and the desktop is awake with Syntheo open.

[← Prompt recipes](recipes.md) · [Help and reference](README.md) · [Next: Keyboard shortcuts →](shortcuts.md) · [Documentation use notice](../NOTICE.md)