A troubleshooting guide

Is Amp down, or is it you?

When an Amp thread fails, it’s Amp, the model provider behind it, or your own credits, login or network. Amp’s status page keeps the first two apart, and the error’s title tells you which of the rest it is.

Open ampcodestatus.com

Check in a minute

Look at Amp's status page

ampcodestatus.com is Amp’s own page. “Amp Agent” covers creating and running threads, and “ampcode.com” the site and settings. The Inference Providers group shows trouble at OpenAI, Anthropic or Google’s Gemini, and Authentication covers logins.

Read the error's title

Amp names the failure in the alert’s title. “Amp Internal Error” or a model provider is their side; out of credits, a quota, a login or “Network Error” is yours. The table below sorts each one.

Run amp usage

amp usage shows your plan’s usage and credit balance. If there’s plenty left and the status page is clear, check your login and network next.

The error says whose side it’s on

Amp retries some failures on its own before it gives up on a turn, and Amp’s docs don’t list its errors, so these are the titles Amp itself shows. They sort into three kinds.

What Amp says	Whose side	What to do
`Amp Internal Error`	Whose side: Amp's	Amp couldn't reach the model provider, or the connection dropped before the answer finished. Amp says plainly that it isn't your network. Try again in a few seconds.
`Model Provider Overloaded`	Whose side: Amp's	The provider behind your model says its servers are overloaded. Try later, and check the Inference Providers group on the status page.
`Out of Credits`	Whose side: Yours	Your included usage and credits are spent. Add paid credits or choose a paid tier; `amp usage` shows the balance. Included usage resets each monthly billing period.
`You've reached your free usage limit`	Whose side: Yours	The free allowance is used up for now. Add credits to carry on straight away, or wait for more free usage.
`Usage Quota Exceeded`	Whose side: Yours	A limit set on your usage. In a workspace it reads “Your workspace usage limit has been reached”, and only a workspace admin can change it.
Not logged in to Amp. Run `amp login` first.	Whose side: Yours	Run `amp login`. The same fix for “Session expired and could not be refreshed” and “Authentication failed”.
`AMP_API_KEY is set and takes precedence over stored credentials.`	Whose side: Yours	A key in your shell is overriding your login, and it may be an old or short-lived one. Unset `AMP_API_KEY`, or set it to an access token from Amp’s settings, which starts with `sgamp_`.
`Network Error`	Whose side: Yours	Amp can’t reach its servers from your Mac. Check your connection and VPN; behind a proxy, set `HTTPS_PROXY`, and `NODE_EXTRA_CA_CERTS` if it inspects TLS.
`Rate Limit Hit`	Whose side: Could be either	Too many requests in a short time. Wait a moment and try again.
`Model Stream Timed Out`	Whose side: Could be either	The model stopped sending before it finished. Try again in a few seconds; if it keeps happening, check the status page, then your connection.

Status page clear and the error keeps coming? Restart Amp so its background update takes effect, check ~/.cache/amp/logs/cli.log, and send it to Amp with amp report-bug.

Or let the menu bar check for you

Hear about an outage before you start debugging

Perch reads ampcodestatus.com for you once you’ve used Amp on your Mac: often while a session is open, less often between them. It watches Amp Agent and ampcode.com, Amp’s own rows. When either shows an outage, a red banner in the menu bar dropdown says so and links to the incident. A slowdown or maintenance shows as a small icon beside Amp’s usage, and every open problem is listed in Settings → General → Integrations.

The banner is for Amp’s own service: an outage at one model provider shows on Amp’s page, under Inference Providers, but not in Perch’s banner. And in the first minutes of an outage the error in your terminal can arrive before the incident does. The same pass tells you when your Amp is out of date, with the command to update it. How Perch watches agent health.

Get Perch — $29 Download for macOS

Questions

Amp outages, answered

Is Amp down right now?

Check ampcodestatus.com, Amp's official status page, and look at Amp Agent and ampcode.com, then the Inference Providers group. If all are operational and you still get errors, the cause is usually your credits, your login or your network, and the error's title says which.

Amp works, but one model doesn't. Is that Amp?

Usually it's the model's provider. Amp's status page has an Inference Providers group for OpenAI, Anthropic and Google’s Gemini, and errors like Model Provider Overloaded come from there. Switching to a model from another provider often gets you going.

Where do I see my Amp credit balance?

Run amp usage, or open your user or workspace settings on ampcode.com. amp usage --details breaks it down, and amp threads usage shows one thread's cost. Included usage resets at the end of each monthly billing period and doesn't roll over.

Does Amp retry on its own?

For some failures, yes. Amp's docs say a turn with an automatic retry pending still counts as running, and a turn that stops with an error is one Amp won't retry itself. Retry that one by hand.

Is there an amp doctor command?

No. amp mcp doctor checks your MCP servers only. For anything else, amp report-bug sends Amp your thread state, client logs and settings, which Amp deletes after 7 days. The CLI's log is at ~/.cache/amp/logs/cli.log.

The same guide for Claude Code, Codex, Devin and Droid.