Skip to content
Multigrid

Errors and troubleshooting

The error strings a model API actually returns, what the numbers inside them mean, and how to tell which of the causes you have before you start changing things.

Every page in this cluster starts from a string somebody pasted into a search box. That is a deliberate constraint: a person reading one of these has a broken thing in front of them right now, and the first job of the page is to say what the message means, not to explain what a language model is.

The second job is the one the existing results skip. Most error pages list every possible cause and leave the reader to try them in whatever order occurs to them, which for a slow failure can cost a day. These pages put a diagnosis section before the remedies: a command to run, a number to read, a field to log, something that narrows six candidates to one. Then the fixes, ordered by how often each is genuinely the answer.

Where a provider’s exact wording varies, the pages give the shape of the error rather than a quotation — the HTTP status, the fields in the body, the exception class, the finish_reason. Shapes are stable across providers and across releases in a way sentences are not.

context_length_exceeded: What It Means and Five Fixes

Read the two numbers in the message, work out which part of your request overflowed, then cut the part that is actually large.

9 min read

401 and 403 From a Model API: The Six Real Causes

401 means the key was not accepted, 403 means it was accepted and not allowed to do this. The two have different fixes and the distinction narrows the search immediately.

8 min read

CUDA Out of Memory: Reading the Message Properly

The four numbers in a CUDA OOM message tell you which of fragmentation, one oversized tensor, or genuine capacity is your problem — and each has a different fix.

11 min read

“Model Not Found” and the Naming Traps Behind It

A 404 on a model name is usually one of five naming traps: an alias that moved, a snapshot that retired, a deployment name, a region, or an account that lacks access.

8 min read

The Model Won’t Call Your Tool

Nine reasons a model answers in prose instead of calling the function you gave it, each with a test that rules it in or out in one request.

11 min read

Empty or Whitespace-Only Completions

An empty completion always has a finish_reason, and that one field tells you which of six causes you have before you read a line of your own code.

8 min read

A Stream That Hangs and Never Finishes

A hung SSE stream is usually buffering at a hop you did not write, and bisecting the hops with curl -N finds it faster than reading any code.

10 min read

Mojibake and Broken Characters in Output

é and � are two different bugs with two different fixes, and which character you see tells you which encoding boundary is broken.

9 min read

Content Filter Triggered on Innocent Input

Three different mechanisms produce what looks like one refusal, and the HTTP status plus finish_reason tells you which of the three you are arguing with.

9 min read

Tokenizer Mismatch: The Bug That Only Appears in Production

When your token count and the provider's disagree, the gap is systematic and measurable — stop estimating and reconcile against the usage field you are already returned.

9 min read

SSL, Proxies and Corporate Networks Blocking a Model API

CERTIFICATE_VERIFY_FAILED behind a corporate network almost always means an inspecting proxy, and the fix is four environment variables rather than disabling verification.

10 min read

502, 503 and 504 From an AI Endpoint

Four hops can produce a 5xx and the body tells you which one did: an HTML error page is an intermediary, a JSON error object is the provider's own application.

9 min read

Your Bill Doubled Overnight: A Triage Runbook

Six queries, in order, that narrow an unexpected LLM bill from the whole system to one caller, one model or one loop.

11 min read

Latency Spikes That Aren’t the Model

Split one latency number into six — DNS, connect, TLS, upload, first token, streaming — and most spikes turn out to be in a phase the model has nothing to do with.

10 min read

The Model Ignores Part of a Long System Prompt

Instructions get dropped for four measurable reasons — position, conflict, count and phrasing — and each one has a rewrite that fixes it.

10 min read

Embedding Search Returns Nonsense

Nine causes of bad vector search, ruled out in an order that puts the catastrophic ones — a model mismatch, a metric mismatch, a stale index — first.

11 min read

Fine-Tuning Job Failed: Reading the Validation Error

Most fine-tuning jobs fail validation on the file, not the training, and a sixty-line linter run locally catches the faults before you wait in a queue.

10 min read

A Docker Build for an AI Project That Takes 40 Minutes

Layer order, a cache mount and the right wheel index account for nearly all of a slow Python ML build, and three commands tell you which one is yours.

10 min read

It Works in the Playground But Not in My Code

A playground fills in seven things you did not specify, and every one of them changes the output. Pin all seven and the difference disappears.

9 min read

Nothing Changed and the Output Changed

An ordered evidence checklist that separates a change you made, a change they made, and ordinary sampling variance — in that order, because two of the three are cheap to rule out.

11 min read

Other topics