Troubleshooting

Troubleshooting

Start with diagnostics

Run phoenix status, phoenix doctor, phoenix config check, and phoenix system. Add --json where supported for machine-readable evidence.

Provider has no credential

Check the provider-specific environment variable, PHOENIX_API_KEY, supported OAuth login state, or the sealed store. phoenix capability reports whether a credential is present without printing it.

A channel refuses messages

Run phoenix channels and phoenix directory. Empty allowlists refuse everyone. Confirm the incoming room, channel, user, nick, sender, or chat id matches the configured identifier type.

HTTP will not start

A bearer token is required. The web UI also requires a username and password. A non-loopback bind without required credentials is refused. Check for a port conflict and run phoenix gateway.

File or URL is refused

File tools stay inside the configured workspace unless explicitly relaxed. Web tools block private and special-use destinations unless private network access is explicitly enabled. Review Security.

Colab cannot form a team

Two distinct configured models and usable credentials are required. Run /models, /colab, and /usage. Unknown quota is acceptable, but a missing credential or unavailable provider is not.

Session data is malformed

Malformed session files are quarantined and incomplete tool exchanges are repaired where safe. Use session list, snapshot, restore, and diff commands to inspect explicit checkpoints.

CI fails

Reproduce the exact four commands in Building. CI uses the current stable Rust toolchain and locked dependencies, so a newly released stable can surface new Clippy lints. The workflow intentionally does not run Dependabot or use third-party action steps.