Troubleshooting

This page is a symptom index. It points you to the right command and the right owner page without copying every setup guide. For a full local health report, start with anyy status and anyy doctor.

How to Use This Page

1. Run the first-step commands below.
2. Match the failing area to the symptom index.
3. Follow the linked page for the detailed fix.
4. If you collect output for someone else, redact secrets and tokens first.

Most commands accept --home PATH; use it whenever you are not sure which profile/home is active.

Isolate The Scope First

Before changing config, confirm whether the problem follows a profile, a resident gateway, one channel, or one session:

anyy profile list
anyy status --home ~/.anyy
anyy gateway status --home ~/.anyy

If only one channel is failing, start with anyy channels doctor CHANNEL. If only one conversation is failing, try /status, /sessions, /history, and /stop from the active surface before editing global config.

First Steps: status & doctor

Check the runtime surface:

anyy status --home ~/.anyy
anyy status --home ~/.anyy --json

status reports the resolved home, profile, default role, timezone, gateway state, gateway listener, cron, heartbeat, storage, and MCP summary. If the gateway is reachable, it merges live gateway status into the local report.

Then run doctor:

anyy doctor --home ~/.anyy
anyy doctor --home ~/.anyy --json

doctor checks filesystem, profile, config validity, timezone, gateway listener, channel config and secret refs, cron, heartbeat, MCP, and storage. JSON output is best for bug reports because every check has name, status, and detail.

Symptom Index

Install & update

Symptom	Check	Next page
anyy is not found	which anyy and anyy --version	Installation
Installed version differs from the running gateway	anyy gateway status	Gateway
Update check fails	anyy update --check --home ~/.anyy	Updating
You need to remove Anyy	anyy uninstall --keep-data --yes or --full --yes	Data, Retention & Deletion

Setup & providers

Symptom	Check	Next page
Config parse or validation failure	anyy config --home ~/.anyy; anyy doctor --home ~/.anyy	Configuration Reference
Provider key missing	Check api_key_ref or credential_ref and the referenced env/file/secret	Credentials & Auth
Wrong model selected	anyy setup model --home ~/.anyy	Configuring Models
Fallback routing is not used	anyy setup model fallback --home ~/.anyy	Configuring Models

Gateway won't start or stay up

Symptom	Check	Next page
TUI works but one-shot chat fails	Start the resident gateway: anyy gateway start	Gateway
Socket cannot be reached	anyy status --socket PATH; inspect anyy.sock and runtime.json	Gateway
Service manager unsupported	anyy gateway status --home ~/.anyy	Running as a Resident Service
Gateway runs an older binary	anyy gateway restart	Updating
Heartbeat is stale or degraded	anyy heartbeat status --home ~/.anyy	Heartbeat

Channels not delivering

Symptom	Check	Next page
Channel config is present but disabled	anyy channels doctor CHANNEL --home ~/.anyy	Channels Reference
Secret ref fails	Resolve the secret:, env:, or file: ref for that channel	Channels Reference
Telegram does not respond	anyy channels doctor telegram --home ~/.anyy	Telegram Setup
A config change was not picked up	anyy channels reload --home ~/.anyy	Messaging Gateway
Live smoke is warn	Set ANYY_LIVE_CHANNEL_TESTS=1 plus the channel's test env vars	Channels Reference

MCP servers failing

Symptom	Check	Next page
Server not listed	anyy mcp list --home ~/.anyy	MCP Config Reference
Server config exists but tools are absent	anyy mcp show SERVER_ID --home ~/.anyy --json	MCP Integration
Server cannot connect	anyy mcp probe SERVER_ID --home ~/.anyy	MCP Integration
Runtime needs a reload	anyy mcp reload [SERVER_ID] --home ~/.anyy	MCP Config Reference

Authentication errors

Symptom	Check	Next page
Env ref is empty	printenv NAME for env:NAME refs	Environment Variables
Profile-local secret is missing	Check ~/.anyy/secrets/<name> for secret:<name> refs	Data, Retention & Deletion
Provider auth profile is unsupported	Check provider profile, auth_mode, and auth_profile	Provider Config
OAuth or external auth needs refresh	Run the provider setup/auth flow again	Credentials & Auth

Performance

Symptom	Check	Next page
State database grows large	anyy status --json storage section	Data, Retention & Deletion
Raw backlog grows	anyy maintenance prune-inactive-sessions --home ~/.anyy	Maintenance
Token estimates missing	anyy maintenance cache-token-estimates --home ~/.anyy --execute	Maintenance
A turn is stuck	Use TUI /stop, /queue, /btw, or /busy interrupt	Sessions

Common Patterns

Pattern	Cause	Fix
Works in TUI, fails from anyy chat	Embedded gateway exists, resident gateway is not reachable	Start the resident gateway for the same home/profile.
Works in default profile, fails in another	Config, secrets, skills, or channel state are profile-local	Run setup or copy only the intended config into that profile.
Doctor passes, live request fails	Doctor is mostly local validation	Run the provider, MCP, or channel-specific live probe.
A secret works in your shell but not as a service	Service manager did not inherit your shell environment	Store it as secret: or inject it into the service environment.

Collecting a Debug Bundle

Use the debug command from an active TUI or compatible command surface when it is available:

/debug

For CLI-only reports, collect these instead:

anyy --version
anyy status --home ~/.anyy --json
anyy doctor --home ~/.anyy --json
anyy gateway status --home ~/.anyy

Do not include raw secret values, bot tokens, OAuth credentials, private channel messages, or full logs that may contain user data. Anyy redacts known secret values, but you should still review anything you share.

Where to Get Help

When asking for help, include:

• Anyy version.
• OS and install method.
• The exact command you ran.
• The relevant status --json and doctor --json checks.
• Whether the issue is tied to one profile/home, one channel, or one session.

Avoid screenshots that expose tokens, channel IDs, private messages, or local filesystem paths you do not want to share.