Operations and troubleshooting

Find the cause first, then use the supported fix.

Most problems have a quick first check. Start with the table, then follow the link. Prefer Synoec’s own commands over editing files: configuration and history have owners, and a hand edit can make things worse.

Symptom → first check

Symptom	First check	More
A model or provider is unavailable	synoec doctor, then synoec status	Provider sign-in, Providers and models
The chat answers with a line about the AI provider	Read it: it says what would help	Provider lines in the chat
Sign in required or API key missing on a provider	Settings → Profiles & Providers	Provider sign-in
A chat shows Response interrupted	Check saved outcome	Recover a conversation
Queued messages did not send after a restart	The queue is paused; choose Resume	Desktop app
Usage shows a missing cost or total	Overview vs. Details; scope toggle	Usage looks wrong
Web search or scraping fails	synoec web doctor search / scrape	Web tools
The agent keeps asking for approval, or never asks	Sandbox level in Settings → Permissions (/permissions in the CLI)	Desktop app
A background command keeps running	The Processes card on the thread rail, then its stop icon	Desktop app
A long chat never compacts, or compacts and loses little	The Context card lists each compaction, skipped ones by cause	Desktop app
Code map or memory seems empty	Project selected? Repository → Code Index status	Repository, Workspaces and memory
Computer Use cannot act	synoec computer-use permissions; Settings → Permissions	Computer Use
Push or pull request fails	gh auth login / glab auth login	Desktop app
The chat list went empty or shows an error	It does not: a failed read keeps the rows shown and retries. Check host-exits.log	Where data lives

Diagnostic commands

Command	Use it to
synoec doctor [--profile <name>]	Check configuration, credentials, providers, storage and core tools
synoec status	Show engine and provider readiness
synoec auth status [--connection <name>]	See whether a credential is stored and ready
synoec config paths|validate|explain	Find files, validate configuration, explain where a value came from
synoec resilience <session>	Explain recovery evidence for a session
synoec diagnostics export [--session <id>] > diag.json	Print bounded diagnostics as JSON to attach to a report
synoec repair projection <session>	Rebuild a session’s saved view
synoec repair delivery <session> <turn>	Repair a stuck message delivery
synoec repair effect <session> <turn> acknowledge|cancel|fail	Settle an interrupted tool effect after you have checked it

repair previews before it changes anything. Settle an interrupted effect only after you know whether it happened.

Provider lines in the chat

When a provider cannot answer, the chat does not show an error mark or a status code. It answers with a plain line that says what would help, for example:

• The AI provider took the request but didn’t answer in time. A local model may still be loading; send your message again. The server accepted the request, so the provider is reachable; a local model reloading its weights looks like this. It is not reported as unreachable.
• You’ve hit the AI provider’s rate limit for now. Wait, then send again.
• The AI provider didn’t accept this connection’s API key or sign-in. See Provider sign-in.
• This conversation has grown too long for this model. Start a new chat or switch to a model with more room.

The exact failure code is kept in the saved receipt and in synoec diagnostics export. Nothing moves a chat off the Profile or connection you selected: fix the connection, or pick another model in the composer. A default connection that is not signed in does not stop the engine.

Recover a conversation

When the app or engine restarts mid-response, the chat shows Response interrupted instead of a running model. Nothing is replayed automatically.

1. Choose Check saved outcome to reconcile results the engine already saved.
2. If the response cannot continue, choose Cancel response. This closes the turn and keeps evidence of any uncertain effect. If either step fails, the card says why.
3. The chat keeps its composer and draft. A quiet Stopped line offers Resume, which continues the stopped turn and keeps completed work; or just send a new message.

Queued follow-ups stay paused after a restart or cancel. See the recovery contract.

Provider sign-in recovery

A missing, expired or rejected credential is reported as an authentication failure, not a model error.

• Desktop. Open Settings → Profiles & Providers. A connection marked Sign in required offers Sign in or Re-authenticate; one marked API key missing offers Update API key.
• CLI. Run synoec auth status, then synoec auth login --connection <name> (add --api-key-stdin to pipe a key). Sign-in opens your system browser.

Signing in does not replay failed work; send the request again. A stored credential is not proof the provider still accepts it, so synoec doctor checks readiness separately.

Usage looks wrong

Usage has three tabs: Overview (usage over time and connection cards), Details and Models. Plans and local models take no budget; set one on an API connection’s card.

• A missing price or token count shows as unavailable, not zero.
• Amounts marked Estimated · not your bill use API rates, not your invoice.
• Provider account cards follow the provider’s own billing window.

From the terminal, synoec usage and synoec usage --refresh-accounts. See Usage and pricing.

Web tools health

synoec web status all shows the selected modes, versions and endpoints. synoec web doctor search|scrape checks the local runtime or remote endpoint, and synoec web repair reinstalls a local runtime. An HTTP 429 is an upstream limit, not a provider login failure. See Tools and integrations.

Where data lives

What	Where
Configuration and history	~/.synoec (or SYNOEC_HOME)
Installed CLI	~/.local by default
Lysis investigations	~/.synoec/lysis/projects/
Project plans and local artifacts	.synoec/ inside the project
Desktop support hosts that ended unasked	host-exits.log in the desktop app’s data folder, with the reason its guardian saw

Synoec keeps the state database small on its own: when a turn ends, settled model steps drop their stored request bodies, and host-command snapshots older than a day are compacted. Memory recall uses one long-lived worker per engine, which stops after two quiet minutes.

Do not move an active database or delete payloads to fix a display problem. Archiving a chat keeps it; Purge… deletes it permanently. See thread purge.

Limits

• Recovery never invents results: an effect with unknown outcome stays marked until you settle it.
• A diagnostics export is printed locally; it is not sent anywhere unless you share it.

Related

CLI · Desktop app · Providers and models ·

Decisions behind this page: 0092 — see the decisions index.