Troubleshooting

Symptom	Check	Next action
Mission fails with a missing executable	CLI location and service PATH	Set an absolute path in host.binaries, then restart through your supervisor
CLI launches but authentication fails	Sign-in under the daemon's OS account	Authenticate the CLI directly, then retry a small mission
Mission fails before producing output	Agent's working directory	Use an existing absolute host path accessible to the daemon
UI cannot reach the daemon	Address, port and authentication	Compare the app's daemon URL with the actual listener
Address already in use	Host app and Compose app both enabled	Keep one web-app serving mode
Configuration rejected	Error names a key	Correct that key or restore the last working file
Plugin visible but refused	Reason on its gallery card	Check API version, licence and signature; repeatedly toggling cannot fix admission
Feature or model missing	Host capabilities, enabled plugins and backend catalogue	Inspect timon doctor, timon module list and timon backends
Quota state unavailable	Whether the backend has a working usage probe	Treat unknown as unknown, not as zero usage

Notification area icon could not be loaded

If Timon reports that its notification area icon could not be loaded, reinstall Timon to restore it. The window remains usable without the tray icon; closing it quits the desktop app. A daemon running as a service stays running, while a daemon running in portable mode stops with the app.

Collect a useful diagnostic

timon doctor --json
timon service status
timon app status
timon plugin list

For a failed mission, retain its ID and error message. Remove tokens, secret values and personal paths before sharing logs. Never post daemon-token, a backend authentication file or the entire Timon data directory.

A container reaching host.docker.internal is using the bridge address; it cannot assume access to a listener bound only to host loopback. Check the Docker setup before changing authentication settings.

Unexpected end of input on macOS (TIM-0011)

This report remains under investigation. A successful HTTP status alone does not prove that a script or JSON response is complete. Empty or malformed sign-in state responses now report [TIM-0011], the endpoint and HTTP status in the renderer console.

For the packaged desktop app, quit Timon completely, then launch a build containing the renderer diagnostic from Terminal:

TIMON_RENDERER_DIAGNOSTICS=1 /Applications/Timon.app/Contents/MacOS/Timon > "$TMPDIR/timon-renderer.log" 2>&1

Leave developer tools closed during capture: opening them can detach the diagnostic session. Wait for the page to load, reload once with Cmd+R, then visit a failing page. Quit Timon and extract the diagnostic records:

grep '"diagnostic":"TIM-0011"' "$TMPDIR/timon-renderer.log" > "$TMPDIR/timon-renderer-diagnostic.jsonl"

Send the extracted file, installed version/build SHA, page name and reproduction steps to support. Look for ready before the reload; attach-failed, enable-failed or detached means collection was unavailable or interrupted. The record limit is 5,000 per window (1,000 successful script records and up to 30 failed-source fingerprints). Relaunch for another capture.

The trace records script IDs, lengths, SHA-256 fingerprints of failed sources, stack locations, isolated execution contexts, HTTP statuses, MIME types and transferred sizes. It does not record source text, response bodies, cookies, headers, exception descriptions, URL query strings or local file paths. Non-bundle URL paths are redacted. Script IDs connect parser failures to stack locations; line and column numbers are zero-based. A script-failed record identifies a parser failure, while a runtime exception can identify a JSON parse caller. No source contents are saved, so a fingerprint may still need comparison with the exact installed build. Worker targets are not collected.

Nothing is uploaded automatically. Normal launches without TIMON_RENDERER_DIAGNOSTICS=1 disable this capture. Delete the temporary logs when finished; the unfiltered log can contain unrelated application output.

Agent editor does not accept typing (TIM-0021)

This Windows report is fixed. If the Name field ever stops accepting typing again and support asks for a focus trace, close the agent editor, open the desktop developer tools (Ctrl+Shift+I on Windows), select Console, and run:

sessionStorage.setItem('timon:diagnostic:agent-editor', '1')

Open Agents → New agent, click Name, type a short test name, then try Tab and the other fields. Filter the console by [TIM-0021] and copy those lines for support. If the shortcut does not open developer tools, report that to support. Note the installed version, Windows display scaling, and whether the issue also happens with the browser panel closed. The trace records element types, focus, hit testing and the name's length, never field contents or typed characters. Nothing is sent automatically. Collection stops after 150 records per editor opening; reopen it for another attempt.

To disable collection, close the editor and run:

sessionStorage.removeItem('timon:diagnostic:agent-editor')

The flag belongs to the current window session. No diagnostic is collected unless explicitly enabled.

Codex is not connected

Run codex login under the same OS account that runs Timon, then retry your message. Setup displays a sign-in warning and lets you check again after login. timon doctor shows the credentials path checked by the daemon: CODEX_AUTH_DIR/auth.json when configured, otherwise .codex/auth.json in that account's home. If you signed in under a different home, configure CODEX_AUTH_DIR for the daemon to point to the directory containing that file.

Timon needs a readable authentication file for subscription login. If your CLI stores credentials only in the OS keyring, sign in with file storage:

codex -c 'cli_auth_credentials_store="file"' login

An existing CODEX_API_KEY or OPENAI_API_KEY also allows launch when stored in Timon's secrets vault in inject mode and granted to the agent (or its project). A daemon environment key is available to missions only with the explicit secrets.inheritEnv setting enabled; this setting inherits the entire daemon environment. A variable set only in your terminal may not reach a service or desktop application. Setup and the diagnostic check the main agent's access. The diagnostic checks local credential availability; it does not contact the provider or verify whether a session has expired.

Web app stops during startup

When the web app port is occupied, Timon waits through five retries for it to be released. The daemon log includes the address and, when the operating system tools are available, the listener PID. Timon does not terminate or adopt an unidentified listener. Close a previous Timon instance or the conflicting application, or change app.listen.port, then relaunch Timon.

A clean exit (code 0 without a signal) receives up to two automatic retries with backoff during a supervision session. A third clean exit stops automatic restarts and produces an alert. A crash still receives bounded retries. Include the exit code, signal and preceding startup logs when reporting either problem. A rebuild is only suggested when the app build is missing or incomplete; packaged users should reinstall a complete package in that case.