Troubleshooting
Resolve missing sessions, blocked requests, locked settings, and CLI launch issues.
Start with the request’s error message and the organization selected in the CLI and console. Change one setting at a time, then send a new request to check the result.
No session or usage appears
- Run
edgee auth statusandedgee auth orgs. - Select the same organization in the console and clear restrictive filters.
- Choose a period containing the session.
- Confirm the agent completed a model request through Edgee, not just started and exited.
- For a manually configured agent, check its endpoint and selected model/provider.
Open Logs: if requests appear there, traffic reached Edgee and the issue concerns session grouping or filters. See Sessions.
A request is rejected
| Symptom | What to check |
|---|---|
| 401 | Missing or invalid credentials: sign in again or check the application’s Gateway API key |
| 403 | Key status, expiration, and model access |
| 429 mentioning a usage limit | Usage limits or the effective Strategy budget; wait for reset or ask an admin to adjust the cap |
| 429 from a provider | Provider rate limit or subscription allowance; inspect eligible fallbacks |
| Model unavailable | Use an allowed catalog model and its exact ID |
| BYOK failure | Test the provider key and check its assignment and BYOK Only settings |
| Stream stops after output starts | Inspect the provider or connection error; a partially delivered stream cannot be transparently restarted |
An exhausted budget needs a reset or adjustment; retrying cannot replenish it. An all-time spending limit never resets automatically. For API error details, see Gateway errors.
A setting is locked or ignored
Check organization settings, then the squad and agent. Explicit organization-level On and Off values are enforced. Inherit delegates the decision. If a Strategy is assigned, inspect its rules and fallback instead of changing an ignored reroute list. See Organization settings.
Costs or savings look unexpected
- Compare the same organization, period, and filters.
- Check the served model/provider when routing changed the request.
- Cached, input, and output tokens have different prices.
- Measured subscription or BYOK usage is not necessarily an Edgee credit charge.
- Compression needs eligible content; a short request may have little to trim.
See Observability to inspect requests and usage.
CLI command or alias fails
Run edgee --version and edgee --help. Update Edgee if a documented command is absent. Reopen your terminal after installing aliases. Try edgee launch claude explicitly to distinguish an alias issue from an agent issue. The target application must already be installed.
For desktop apps, close existing instances and launch through Edgee again. Check the agent guide for supported platforms and app surfaces.
See Aliases. For the Claude Code statusline, run edgee statusline claude doctor; see Statusline.
An alert does not fire
Check that the rule is enabled, its threshold and window are correct, and a notification channel is configured. Percentage alerts require a usage limit on the selected scope. Review Alerts history before diagnosing email or Slack delivery. See Alerts.
Ask for help
Include the CLI version, operating system, agent, error message, request/session ID, approximate time, and what you checked. Remove keys, tokens, passphrases, emails, and private request content. Contact Edgee support.