Troubleshooting

Running diagnostics

traces doctor

This checks:

• CLI binary is on your PATH and executable
• Local SQLite database exists and is readable
• Authentication credentials are present and valid
• Network connectivity to the Traces API
• Agent detection and hook configuration

Resetting local state

# Delete local database (synced traces are unaffected)
traces reset

# Also clear stored credentials
traces reset --all

# Skip confirmation
traces reset --force --all

Authentication problems

Login hangs or fails to open a browser

traces login --no-browser

Prints a URL you can open in any browser.

"Not authenticated" errors after login

traces whoami           # check credentials
traces reset --all      # clear and re-authenticate
traces login

Token expired

Tokens refresh automatically. If you see token errors:

traces logout
traces login

Agent not detected

1. Run traces setup to install or reinstall hooks
2. Confirm your agent is supported
3. Check the agent is running in a directory Traces can observe
4. Run traces doctor to verify hooks

If you recently updated your agent, re-run traces setup -- hook paths may have changed.

Large session warnings

Sessions with many messages may show a confirmation prompt before sharing. This is normal for long sessions. To reduce size, break long sessions into smaller tasks.

Permission issues

Database permission denied

Run traces status to find your local database path, then confirm your current user can read/write that directory.

If permissions were changed by another process, restore ownership for your user account and run traces doctor again.

Binary not found

Ensure the installation directory is on your PATH:

which traces

# If not found, add to your shell profile:
export PATH="$HOME/.local/bin:$PATH"

Network and sync issues

Traces not appearing on the web

1. Check network connection
2. Run traces status to confirm auth and database health
3. Verify namespace with traces whoami
4. Wait a few seconds for background sync and refresh

Timeouts or slow syncs

Large traces take longer to upload. Run traces doctor to verify API connectivity.