“`finishReason`: `length`”, “`content-filter`”, “`error`”, “`other`” — and the second field the Vercel AI SDK kept the real answer in

The Vercel AI SDK is a single interface over many model providers, and finishReason is the field where that ambition costs you something: every provider’s way of saying why it stopped is mapped into the six values above. Two of those values, error and other, carry almost no information by construction — they are the buckets a reason falls into when it did not fit the other four. The useful part is that the SDK did not throw the original away. It is documented to hand you a second field, on the same object, holding the provider’s own string.

In ten seconds. If you got error or other, read rawFinishReason. The generateText reference documents it, right beneath finishReason, as “The raw reason why the generation finished (from the provider).” Your provider’s actual termination reason — the string it sent over the wire — did not vanish when the SDK normalised it into a six-value union. It is in that field. Its type is string | undefined, so check it before you trust it.

Then, per value. length points at a token ceiling, and the SDK documents two of them, one of which is per step. content-filter is not only a safety path: the AI SDK’s own troubleshooting documentation records a case where it is produced by an incompatible Zod schema, with no unsafe content anywhere in the request. stop is the ordinary success value and is not this page’s problem.

The field, and the field next to it

These two lines are adjacent in the return value documented for generateText. Quoted as published:

That pairing is the whole trick of this page. One field is normalised and lossy; the field immediately after it is the provider’s own text. The same pair is documented on streamText, where both arrive as promises because reading them consumes the stream:

And the same pair again in the prose guide to generating text, in the form you will actually type:

- `result.finishReason`: The reason the model finished generating text. - `result.rawFinishReason`: The raw reason why the generation finished (from the provider).

The word the reference uses for the first field is worth noticing. In the per-step documentation it is called not just the reason but “The unified reason why the generation finished” — unified being the admission that something was flattened to get there. rawFinishReason is the unflattened one.

Where to read them, including mid-run

Both fields are documented in more than one place on the response, and the distinction matters if you are using tools or multiple steps. They appear on the top-level result, and they also appear on each step, so a run that ends stop overall can contain a step that ended for another reason entirely. The step-level documentation reads:

The SDK’s own example of a synthesised stream event shows the two side by side, which is the clearest picture of their relationship in the documentation — the normalised value and the raw value set to the same thing, because for an ordinary stop there is nothing to lose:

controller.enqueue({ type: 'finish-step', finishReason: 'stop', rawFinishReason: 'stop',

Where the two differ is exactly where you need the raw one.

`length` — two ceilings, and one of them is per step

For a generation that stopped because it ran out of room, the lever the SDK documents is maxOutputTokens. The reference describes it plainly:

- `maxOutputTokens?` (`number`): Maximum number of tokens to generate.

The part that catches people is that this setting is documented a second time at the step level, with its own fallback behaviour:

- `maxOutputTokens?` (`number`): Maximum number of tokens to generate for this step. Uses the top-level value when omitted or undefined.

So a generous top-level budget does not guarantee a generous step. To confirm a ceiling was the cause rather than assume it, compare what you allowed against what was spent. The usage object on the result documents the figure you want:

- `outputTokens` (`number | undefined`): The number of total output (completion) tokens used.

If finishReason is length and usage.outputTokens has arrived at the ceiling that was in force for that step, you have your answer and the fix is a larger ceiling or a shorter task. If it stopped well short of the ceiling, the ceiling is not what bit you, and rawFinishReason is the next thing to print — the provider may have been describing a different limit, and a length in the union can be a provider string the SDK mapped there.

One more thing to check before blaming the model: the SDK warns that not every setting survives every provider. “Some providers do not support all common settings. If you use a setting with a provider that does not support it, a warning will be generated. You can check the warnings property in the result object to see if any warnings were generated.” A ceiling that was silently dropped is a ceiling that was not applied, and the warnings property is where that is recorded.

`content-filter` — the documented cause that is not about unsafe content

This is the value most likely to send you looking in the wrong place, because its name tells you a story about moderation and at least one documented cause has nothing to do with moderation. The AI SDK’s troubleshooting documentation carries an entry titled “Object generation failed with OpenAI”, and it opens:

When using structured output generation with OpenAI, you may encounter a `NoObjectGeneratedError` with the finish reason `content-filter`. This error occurs when your Zod schema contains incompatible types that OpenAI's structured output feature cannot process.

The mechanism is spelled out, and it is a schema-shape problem wearing a safety label:

The Zod methods `.nullish()` and `.optional()` generate JSON Schema patterns that are incompatible with OpenAI's implementation, causing the model to reject the schema and return a content-filter finish reason.

The error as it reaches you is quoted in that document too, and it is the string people paste into a search box:

// Error: NoObjectGeneratedError: No object generated. // Finish reason: content-filter

The fix given is a one-word substitution in your schema:

Replace `.nullish()` and `.optional()` with `.nullable()` in your Zod schemas when using structured output generation with OpenAI models.

So the procedure for a content-filter is: if you are generating structured output, check your schema for .optional() and .nullish() first, because that cause is documented and cheap to rule out. If you are not, or your schema is clean, print rawFinishReason — a safety stop and a schema rejection both normalise to the same union value, and the provider’s own string is the thing that still distinguishes them.

`error` and `other` — one instruction

These two are the residual categories of the union, and there is only one useful move, which is the sentence this page exists to say: the reason you are missing is in rawFinishReason. Log it before you do anything else.

const result = await generateText({ /* ... */ }); if (result.finishReason === 'error' || result.finishReason === 'other') { console.log(result.finishReason, result.rawFinishReason); }

With streamText, both are promises, so await them — and note the reference’s warning that reading finishReason “Automatically consumes the stream”, which is a side effect you want to be deliberate about rather than surprised by. If you are stepping through tool calls, read the step-level pair as well as the top-level one: the step that failed is not always the step that finished the run.

Because the type is string | undefined, write the undefined branch. A field documented as optionally absent will eventually be absent, and an other with no raw string next to it is a genuinely different situation from an other with one — worth distinguishing in your own logs so you can tell which you are looking at later.

What we checked, and the one thing we looked for and did not find

Everything quoted above was read from the AI SDK documentation on the day this page was written. The six-value union is identical on the generateText and streamText references, and rawFinishReason is documented with the same sentence each time it appears beside it.

One negative result, stated with its basis so you can judge it. The AI SDK publishes a machine-readable semantic sitemap of its documentation. We fetched that sitemap — 122,874 bytes — and searched it: the string FinishReason appears in it zero times, and the word “finish” appears twice, in neither case as a page about this type. So as the documentation indexes itself, there is no page dedicated to the FinishReason type; what exists is the field documentation on the function references, which is what this page quotes. The type name FinishReason is nonetheless used as a type annotation on both references, so the type is real — it just does not have a page of its own in that index.

We make no claim about what any provider sends in rawFinishReason, because that is each provider’s string and not the SDK’s. That is the point of the field, and the reason printing it beats guessing at it.

There is a written guide: the step-and-turn arithmetic as a formula you can run against a brief before you launch it, why raising a cap does not finish the job, and batch.py, one standard-library file that collapses a per-item loop into a single pass. It is $19, on a storefront that delivers the files automatically and carries a 30-day money-back guarantee (checked 2 October 2026). One working way to pay today is 19 USDC on Base, and delivery is manual: you email the transaction hash and the files come back as a reply. This page is free, ungated, and sells nothing on its own.

The short version: the Vercel AI SDK normalises every provider’s termination into finishReason, documented as 'stop' | 'length' | 'content-filter' | 'tool-calls' | 'error' | 'other', and keeps the provider’s own string in the field beside it, rawFinishReason — string | undefined, documented as “The raw reason why the generation finished (from the provider).” If you got error or other, that field is where your actual reason went, and both fields exist on each step as well as on the top-level result. For length, maxOutputTokens is documented both top-level and per step, the per-step one falling back to the top-level value when undefined, so compare usage.outputTokens against the ceiling that was actually in force and check warnings in case the setting was not supported at all. For content-filter, the SDK’s troubleshooting documentation records a cause that is not a moderation event: .optional() and .nullish() in a Zod schema used for OpenAI structured output, fixed by .nullable().

Nearby

finishReason: tool-calls — the fifth value of this same union, and the only one that is not a problem but an instruction: the model is waiting for you to run something.
finishReason: SAFETY, RECITATION, OTHER — the same shape of problem one layer down, at a provider whose own enum has twenty-two values and defines eleven of them with their own names.
model_context_window_exceeded — the other kind of running out of room, where the limit is the window rather than the output ceiling.
stop_reason: refusal — a safety stop arriving on a successful response at another vendor, and what that response object carries instead.

This page counts anonymous readership with one counter, the file at /measure.js, and each of the events below is sent at most once per load. Once the page is ready it sends one view event. With it go the page path, the domain of the page you came from — only the domain, and nothing at all if you came from this site — how long the page has been open, counting only the time it was actually in front of you and not the time it sat in a background tab, whether you have scrolled, and any campaign or outreach code in the link you followed. A second event, which we call a human candidate, is sent only once the page has also received a real input event from you — a mouse movement, a touch, a scroll or a key press — and has been visible in the foreground for ten seconds in all; a program that fetches the page, or opens it and sits there, cannot produce one. A third, “engaged”, is stricter still: it is sent only after the human-candidate event, once the page has been in front of you for ninety seconds in all and you have scrolled far enough to reach a marker we put where the explaining part of this page ends; a reader who stops short of that marker never produces one. The second and third events carry the same fields as the first. If you switch away from the tab or close it, an event that has just become due may be sent as you leave. If this page has a button or a copy control that says it records a click, pressing it sends the name of that event and nothing else. Following a link to buy the guide sends one further event, also at most once per load, carrying that event’s name and a single word for which of the two checkouts you were sent to — the Gumroad listing or the payment page on this site — and nothing else: not the address you followed, not which page you were reading, not how long you had been there. Everything is sent to this site only, with no cookie attached. No cookie is read or written, nothing is put in your browser’s local or session storage, and no identifier is made from your device. Earlier versions of this page kept the campaign codes of your first visit in local storage under the name llab_attr; this page neither reads nor deletes that entry, so if it is there it stays until you clear this site’s data. An outreach code is minted per recipient, which would let us tell one reader from another; it is sent with each event and, unlike on earlier versions of this page, it is no longer removed from the address bar after it is read — if you copy the address, the code goes with it. Earlier versions also asked this domain for Vercel’s analytics script at /_vercel/insights/script.js, which on 26 September 2026 returned HTTP 404 on every host we publish; this page no longer asks for it. Your browser and the network attach things the page does not send: the identification string your browser gives, your IP address and the time of the request. The host that serves this page keeps its own request logs; those are its record and not ours.

“finishReason: length”, “content-filter”, “error”, “other” — and the second field the Vercel AI SDK kept the real answer in