Troubleshooting and shortcuts

© 2026 Quadropic Pvt Ltd. Proprietary and confidential. Use restrictions.

Fast diagnosis#

Model and provider problems#

“No provider configured” or send opens AI Provider#

1. Open Settings → AI Provider.
2. Find the lane used by the selected preset/action.
3. Choose an available provider and model.
4. Save an API key or complete OAuth.
5. If using Ask from Standard, also verify Light.
6. If using Architect or Debug from Standard, verify Hunter.

If a model is labeled unavailable, its saved ID is no longer present in the provider catalog. Select a current model or restore the custom endpoint.

Authentication fails#

• Confirm the credential belongs to the selected provider.
• Check whether the lane is configured for Key or OAuth.
• For an existing Claude subscription use Anthropic OAuth; for ChatGPT Plus/Pro use OpenAI Codex OAuth, not the regular OpenAI key provider.
• For OAuth, retry Authenticate or refresh the token.
• For a custom endpoint, verify base URL, API dialect, and optional key environment variable.
• Do not paste secrets into the chat for diagnosis.

Context meter is clearly wrong#

For custom models, correct the configured context window. For catalog models, switch away and back after provider metadata refresh. Treat the lower known limit as authoritative until verified.

Workspace and file problems#

The agent edits the wrong project#

Stop the run immediately with ⌘Esc / Ctrl+Esc.

Then:

1. Inspect the task’s workspace label.
2. Check whether it inherited a room worktree or owns a Virtual Edit.
3. Run pwd and git status --short --branch in the task Terminal.
4. Preserve and classify any edits before changing directories.
5. Start a new thread in the correct workspace if the boundary was wrong.

Do not “clean up” with a destructive Git reset.

A file does not appear in @ search#

• Confirm the composer’s selected workspace.
• Type more of the relative path.
• Check whether the file is ignored, generated, or outside the workspace.
• Add the correct directory as a separate workspace if it is legitimately out of scope.

Search results are irrelevant#

Use concrete symbols and domain nouns. Replace:

How does this work?

with:

Trace checkout session renewal and account-state persistence.

Mention the nearest known file and ask the agent to trace outward.

Run, approval, and context problems#

The agent is waiting#

Look for:

• the hand/attention indicator in the sidebar;
• a tool approval card;
• a structured question;
• a pending request in a sub-agent tool card;
• system-tray “needs input.”

If several approvals are pending, use left/right arrows to navigate the approval dock.

An approval is no longer pending#

The run may have stopped, timed out, or already handled the request. Refresh/open the task and inspect its latest status. Do not repeat a side-effecting command until you know whether the first call executed.

The run is stuck in a bad direction#

Send one steering delta. If it does not correct course, stop and restart with:

• the same observable outcome;
• corrected evidence;
• discarded hypothesis;
• explicit next inspection target.

Do not stack several contradictory steering messages.

“Request too large” or context over 90%#

If the objective is unchanged, compress using ⌘⌥C / Ctrl+Alt+C, then restate authoritative constraints. If the objective changed, start a new thread.

If compression fails:

• remove unnecessary draft images;
• start a new thread;
• mention durable files/plans instead of pasting old history;
• use a model lane with a verified larger context window only when the additional context is actually useful.

A run stopped#

Read the run card:

• stopped means a user/system stop was processed;
• failed includes the provider, tool, or runtime error;
• an Autonomy task may show interrupted/paused and can be resumed.

Before retrying a side-effecting task, inspect current files and external state. A failed final response does not prove that earlier tool calls were rolled back.

Git and diff problems#

File Diff shows no changes#

The panel reflects captured edit artifacts, not the full repository truth. Run:

git status --short --branch
git diff
git diff --cached

Generated files, external editor changes, or commands that rewrite files may not have a line-level widget.

Virtual Edit cannot be created#

Check:

• the workspace is a valid Git repository;
• there is a selected workspace;
• Git can create a worktree and branch;
• the managed worktree location is writable;
• a stale worktree entry is not blocking the branch.

Ask the agent to inspect git worktree list before changing any worktree metadata.

Apply Layer fails#

The base branch and layer may conflict or the base working tree may be dirty. Preserve both states, inspect the error, and choose a deliberate integration strategy. Do not delete the layer until its unique changes are backed up or integrated.

Commit contains the wrong files#

Add Current Changes stages everything. Before committing:

git diff --cached --name-status
git diff --cached

If the commit has not been shared, choose a correction consistent with your Git policy. If it has been pushed/shared, prefer a follow-up commit unless history rewriting is explicitly authorized.

Pull or Sync refuses#

Pull uses --ff-only, so divergence is intentional failure. Fetch and inspect:

git status --short --branch
git fetch --all --prune
git log --oneline --decorate --graph --max-count=30 --all

Then decide whether to rebase, merge, or keep branches separate.

Autonomy and Conductor problems#

Task card exists but no agent is running#

Creating a manager task only stages a card. Open its menu and choose Run, or tell Conductor:

Start every task you created for this objective and verify each is In Progress.

Two agents collide#

Stop at least one writer. Assign exclusive files or subsystems, nominate an integration owner, and communicate current worktree state. In a shared room worktree, changes are immediately visible; “different task” does not mean “different filesystem.”

A room agent cannot see another agent’s changes#

Check its worktree mode:

• Inherit sees the room worktree;
• Detached uses the base workspace;
• Child uses its own worktree.

Move or recreate the task with the intended mode. Do not copy changes manually before identifying the source branch/worktree.

Room history is cluttered#

Archive completed agents, remove abandoned idle tasks, and keep General Hall for triage. Use named rooms for durable initiatives and delete rooms only after handling their worktrees and artifacts.

Marketplace problems#

Skill does not influence the task#

• Confirm it is enabled.
• If User invoked, add it with @ in the same turn.
• Verify you selected the intended Skill when a source contains several packages.
• Read its trigger and ensure the request matches.

MCP tools are not discovered#

1. Confirm the server is enabled.
2. Use Refresh MCP tools.
3. Read the displayed refresh error.
4. For stdio, verify command, arguments, environment, and executable availability.
5. For HTTP/SSE, verify URL, TLS, authentication, and network.
6. If User invoked, mention the exact tool with @.
7. Refresh Settings → Permissions after discovery.

MCP call is denied or repeatedly asks#

The tool’s current permission is Ask. Approve once/turn, or set the individual tool to Allow after evaluating its full capability. If it does not appear in Permissions, refresh both Marketplace and Permissions.

Schedule and mobile problems#

Schedule is overdue or missing#

• Syntheo must be open.
• The machine must be awake.
• The schedule must be enabled.
• The stored timezone and cron must match your intent.
• The target directories must still exist.
• Required provider credentials and permissions must be available.

Use Run now and inspect the resulting task before changing the cron.

Schedule repeatedly creates unwanted changes#

Disable it first. Inspect every run’s workspace and Git state, then make the prompt idempotent and add explicit no-commit/no-push boundaries. Test manually before re-enabling.

Local phone pairing fails#

• Put phone and desktop on the same reachable network.
• Rotate to a New code.
• Use the manual address and code.
• Check local firewall/VPN isolation.
• Keep the Mobile Companion settings page open while pairing.

Remote companion fails#

• Require a wss:// public URL.
• Check relay status and error.
• Confirm the desktop has outbound network access.
• Confirm the phone can reach the relay.
• Turn the relay off and back on only after recording the error.
• Remember that remote access requires the desktop and Syntheo to remain online.

Keyboard shortcuts#

⌘ means Command on macOS. On Windows/Linux use Control unless the row specifies otherwise.

Navigation and surfaces#

Composer and task#

Mentions, approvals, and dialogs#

Global shortcuts can be owned by the application menu. If another application or operating-system shortcut intercepts one, use the visible top-bar control.