`ContentFilterError` — Pydantic AI’s `finish_reason='content_filter'`

Content filter triggered. Finish reason: 'content_filter'

If you pasted that line, or the exception name above it, into a search box, a Pydantic AI agent run ended because the model provider filtered the response. Here is what the Pydantic AI docs say about when it is raised, read off them today, and the case they describe where it is not raised at all.

What the vendor says it means

The exceptions reference, at pydantic.dev/docs/ai/api/pydantic-ai/exceptions/, defines it in one line, with its base class:

ContentFilterError Bases: UnexpectedModelBehavior Raised when content filtering is triggered by the model provider.

The filter is the provider’s, not Pydantic AI’s. 'content_filter' is Pydantic AI’s name for it. The messages reference types FinishReason as Literal['stop', 'length', 'content_filter', 'tool_call', 'error'], “Mostly normalized to OpenTelemetry semantic convention values.” So the provider’s own word for the block has been translated. For Gemini, the Gemini Live page says refused input or unsafe output becomes 'content_filter' and the raw reason is kept in provider_details['finish_reason'].

The message at the top of this page is the one the docs’ own example prints from exc.message, on the Raise Content Filter Error page.

When it is raised, and when it is not

The models overview, at pydantic.dev/docs/ai/models/overview/, says the agent loop “only acts on a finish reason when the response has no actionable output”, and that “an empty or thinking-only response with a 'content_filter' finish reason raises ContentFilterError.”

The other half is on the Raise Content Filter Error page:

By default, Pydantic AI only raises ContentFilterError when a content_filter response is empty: if the provider returns partial text or refusal text alongside finish_reason='content_filter', that text becomes ordinary agent output and no error is raised

So there are two outcomes from the same provider decision. If nothing came back, you get the exception. If some text came back, a fragment or a polite refusal, the run can succeed with that text as its output. The exception is the visible case. The run that succeeded on a refusal is the one nobody notices.

Why your fallback did not catch it

The models overview is direct about this. These errors “are raised from the agent loop, after model.request() has already returned successfully, so no exception-based fallback_on can catch them -- not the default fallback_on=(ModelAPIError,) (which wouldn’t match anyway, as ContentFilterError inherits from UnexpectedModelBehavior, not ModelAPIError), and not an explicit fallback_on=(ContentFilterError,) either.” If you wrapped your model in a FallbackModel and expected the next model to take over, this is why it did not.

The fix

Catch it as its own case. Handle ContentFilterError apart from ModelAPIError. One is a provider decision about content, the other a failed request, and a retry loop written for the second does nothing useful for the first.
Make the silent case loud. Add the RaiseContentFilterError capability. The docs say it “extends the check to every content_filter response, so partial and refusal text raise too”, and that “the full ModelResponse is serialized into ContentFilterError.body so the partial text remains inspectable.” From the docs’ example, with your own model in place of theirs:

from pydantic_ai.capabilities import RaiseContentFilterError agent = Agent(model, capabilities=[RaiseContentFilterError()])

To fall back to another model, use a response handler. The models overview’s example passes fallback_on=bad_finish_reason, a function that returns reason in ('length', 'content_filter', 'error'). Read its warning too: a single response handler “replaces the default (ModelAPIError,) exception fallback entirely”, so pass both together as a list if you still want API errors to fall back.
If you retry, change something. Change the prompt, as the image generation guide’s own except ContentFilterError example does, or change the model, as the fallback example does. Read provider_details['finish_reason'] first, so you know which block you are working around.

The costly version of this is not the exception. It is the run that finished on a refusal and wrote it down as the answer. An agent that checks the finish reason on every turn catches both. One that checks only for exceptions catches half.

What is behind this site

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 Gumroad storefront. One working way to pay today is 19 USDC on Base: you email the transaction hash and the guide is delivered by email. This page is free, ungated, and sells nothing on its own.

The short version: ContentFilterError is “Raised when content filtering is triggered by the model provider.” By default Pydantic AI raises it only when the filtered response is empty. If text came back, that text becomes the run’s output and nothing is raised. It is an UnexpectedModelBehavior, not a ModelAPIError, and no exception-based fallback_on catches it. Add RaiseContentFilterError to make every filtered response raise, and use a response handler to fall back on it.

Nearby

finishReason: content-filter — the Vercel AI SDK’s version, where the provider’s own reason survives in rawFinishReason.
request_limit of 50 — the other way a Pydantic AI run ends early: it runs out of model requests.
finishReason: SAFETY, RECITATION, OTHER — Gemini’s own names for the blocks that reach Pydantic AI as content_filter.
stop_reason: refusal — a safety decline delivered as an HTTP 200 with empty content.

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.

ContentFilterError — Pydantic AI’s finish_reason='content_filter'