On this page
Troubleshooting
Start with:
sigil doctorUse sigil doctor --output json when you need a redacted diagnostic file for a support request. The checks below cover the most common next steps.
Decision Tree
| Symptom | First check | Next action |
|---|---|---|
| Setup keeps reopening | Connection readiness | Reopen /config and save one ready connection and model |
| The model list looks wrong | Selected connection | Confirm the connection-id/model-id; never expect models from another connection |
| Wrong files appear | Workspace path | Restart from the intended directory |
| A tool is blocked | Approval or sandbox message | Review the reason; change policy only if intended |
| MCP is unavailable | /config → MCP Servers | Fix auth, config, or start mode |
| Terminal input behaves oddly | Terminal support | Try a supported terminal and run Doctor |
| A session asks for route recovery | session:route_resume in Doctor | Confirm the intended connection or select a replacement |
| A session is already active | Other TUI/Desktop owner | Exit that owner, retry, or start a new session |
| Context is nearly full | Info rail | Finish the current step or use /compact when available |
Quick Setup Opens Every Time
Sigil has no usable provider connection, credential, or saved model route. Open /config, choose a provider, credential source, and model, then review and save. Quick Setup asks for at most those three decisions. Run sigil doctor and confirm a compound default=connection-id/model-id. For exact fields, see Providers and Configuration Reference.
Sigil Cannot Find The API Key
Check that the environment-variable name belongs to the selected connection and that the terminal launching Sigil inherited it. Restart Sigil after changing shell variables. For a stored credential, reopen /config and repair that connection. The default file and non-interactive auto modes use only owner-only ~/.sigil/credentials.json and never query an older native-system record. If the file-backed record is missing, enter the key once in /config. Never put an API key in sigil.toml or an issue report.
Provider Connection Or Model Catalog Is Not Ready
sigil doctor reports each connection independently and never prints secret values or credential IDs. Match the result to the UI state:
The model catalog is not a prerequisite for saving configuration. If an endpoint has no discovery API or refresh is temporarily unavailable, enter an exact model ID and continue. Only a successful generation request proves that the credential, endpoint, and model route work together.
| State | Meaning | Action |
|---|---|---|
needs_credential / credential_unavailable | The selected source is missing or the configured store cannot read it | Repair that connection's environment binding or stored record; verify [storage].credential_store |
auth_rejected | The catalog request rejected this connection's credential | You may still save an exact model ID; replace the credential if the first generation request also fails |
offline, tls_rejected, protocol_mismatch | Catalog discovery cannot currently use the configured route | Save an exact model ID if known, and check network, TLS, endpoint, and protocol |
remote_empty | Discovery succeeded but returned no models | Enter an exact model ID manually |
catalog_unsupported | This provider/endpoint does not expose discovery | Use the provider-owned bundled list or manual entry |
catalog_malformed | The response was not a valid catalog | Enter the model ID manually; remote metadata is not trusted to add capabilities |
Provider generation and remote model discovery both honor the standard HTTP_PROXY, HTTPS_PROXY, and NO_PROXY environment variables. The [web].proxy_mode setting governs Web tools; it does not configure provider traffic.
If Doctor reports an invalid or incompatible provider configuration, replace it with a current config_version = 2 connection template. Sigil does not migrate or infer older provider blocks. Desktop still opens the selected workspace in a configuration recovery state: open Settings, choose Replace invalid configuration, review the provider, credential source, and exact model, then confirm the replacement. The TUI opens Quick Setup and labels its final action replace invalid config and start. Both paths recheck the live file under the configuration lock and refuse to overwrite a configuration that has become valid concurrently. Do not add duplicate connections or hand-edit credential IDs.
Theme Colors Are Hard To Read
Open /config, choose Appearance, and change the theme or syntax style. You can also disable the info rail. See Appearance.
The Wrong Workspace Is Being Used
Check the directory where Sigil was started and the configured workspace.root. Restart from the intended directory, or edit the active sigil.toml; workspace.root = "." follows the launch directory.
External-directory access is disabled by default. See Permissions And Sandbox.
A File Tool Cannot Access A Path
Read the tool-card error first. Confirm that the path is inside the workspace, is not excluded by policy, and is not a symlink escape. If access is intentional, configure the narrowest additional root; do not broaden access just to silence the error.
A Tool Needs Approval In Headless run
Headless mode cannot show an approval modal. Use a policy that permits the intended action, or run the task interactively. Never use a broader policy than the automation requires.
An Approval Was Denied, Expired, Or Cancelled
The action did not run. A denial records an explicit user decision; expiry, process cancellation, and stale recovery are separate terminal outcomes and never fabricate that decision. Inspect the approval card or audit reason, correct the request if needed, and retry. Sigil never continues an expired or cancelled operation silently.
Mouse Or Clipboard Does Not Work
Check [terminal].mouse_capture and osc52_clipboard in the active sigil.toml, restart after changes, then drag-select plain transcript text. Releasing the mouse copies automatically through the system clipboard and, when enabled, OSC52. A failed copy keeps the selection for Ctrl-C retry. Ctrl-L copies an active selection or the latest assistant reply when none is active. Remote shells and containers may expose neither copy method; image paste separately requires a supported system clipboard. See Terminal Compatibility.
Attention Notification Does Not Appear
Notifications are off by default and depend on terminal support. Enable them under /config → Terminal, run Doctor, and ensure the terminal has not disabled OSC or bell notifications.
A Session Needs Route Recovery
Run sigil doctor and inspect session:route_resume. Endpoint path corrections on the same trusted origin are rebound automatically and do not contact the provider during startup. A changed origin or account/tenant boundary, a missing connection, or an older session without a proven trust binding requires an explicit decision. Review and save the intended connection in /config or Desktop Settings, select a replacement route, or start a new session. Sigil keeps the shell and portable transcript available and does not silently send history to an unconfirmed destination.
A Session Is Already Active
The session has a write-capable owner in another TUI, Desktop run, or headless run. Return to that owner or exit it, then retry the explicit resume. You can also start a new session or return to the session library. The operating system releases the attachment after a normal exit or crash; do not delete the sidecar lock file or force a takeover.
Session Restore Shows Interrupted Tools
Sigil records work that was running when the process stopped as interrupted; it does not replay the command automatically. Review the tool card and retry only if the action is still needed.
Context Usage Is High
The info rail shows context pressure. Finish or checkpoint the current work before starting a large new request. /compact is available only when Sigil can safely apply it for the selected model; otherwise start a fresh or forked conversation. See User Guide.
MCP Server Is Missing, Failed, Or Deferred
Open /config → MCP Servers and inspect the server state:
- missing/failed: check the command or URL, authentication, and logs;
- deferred: activate the server before using its tools;
- needs sign-in: open
/config→ MCP Servers → Authentication.
For OAuth, use only the newest sign-in tab or complete callback URL. A failed remote revocation keeps the local credential and reports an error. You can retry revocation or explicitly choose clear local only; clearing local does not claim the remote token was revoked. Credential-store, callback, refresh, destination, and 401 recovery steps live in MCP.
Code Intelligence Is Not Ready
Run Doctor and check that the language tool is installed and available in the same environment that launched Sigil. Sigil may continue with reduced context when a language service is unavailable; the tool card reports that limitation.
Command Not Found After Install
Open a new shell and check that the package manager's binary directory is on PATH. If multiple copies exist, run command -v sigil (or Get-Command sigil in PowerShell) and remove the stale one. Reinstall commands live only in Installation.
Report A Bug
Run sigil doctor --output json or use /feedback, review the exported file, and attach it manually to the relevant GitHub form. Include the observed result, expected result, reproduction steps, platform and terminal, and the smallest safe log excerpt. Remove project content and secrets; reports are never uploaded automatically.