Error types
Genkit classifies failures with a status, and that classification decides what the
framework does with the error: which HTTP code a flow server answers with, whether
retry and fallback middleware act on it, and what the Dev UI shows. The
github.com/firebase/genkit/go/core/status package holds one error type,
status.Error, and one vocabulary of statuses shared with the other Genkit SDKs.
The pattern is three steps: classify once at the source, add context as the error
travels, and branch with errors.Is. The
basic-errors sample
is a runnable tour of all three, plus the boundary behavior described below.
Classify at the source
Section titled “Classify at the source”status.Errorf builds a classified error from a sentinel and a fmt-style message.
status.PublicErrorf is the same call for a message that is safe to return to a
client; anything built with status.Errorf stays server-side.
Sentinels are ordinary values, so you can declare your own with Subtype. A subtype
keeps its parent’s status and still matches the parent under errors.Is, which lets
each caller branch at whichever granularity it cares about.
import ( "strings"
"github.com/firebase/genkit/go/core/status")
// ErrRecipeNotFound classifies lookups for dishes the cookbook doesn't have.// A subtype keeps its parent's status, so this is still a NOT_FOUND.var ErrRecipeNotFound = status.ErrNotFound.Subtype("recipe not found")
func lookupRecipe(dish string) (string, error) { recipe, ok := cookbook[strings.ToLower(dish)] if !ok { // The message only reflects what the caller sent, so PublicErrorf // returns it to them. return "", status.PublicErrorf(ErrRecipeNotFound, "no recipe for %q in the cookbook", dish) } return recipe, nil}Classify where the failure mode is known, and only there. Code further up the stack should not reclassify, because it has less information than the site that raised the error, not more.
Add context as the error travels
Section titled “Add context as the error travels”Wrap with fmt.Errorf and %w. Wrapping does not reclassify: the sentinel, the
status, and the public message all stay reachable through the wrapper.
recipe, err := lookupRecipe(dish)if err != nil { // %w keeps the sentinel, the status, and the public message reachable, // so this still answers 404 with the message lookupRecipe wrote. return "", fmt.Errorf("could not look up the recipe: %w", err)}Use %w and not %v. %v flattens the error to text and throws the classification
away, which is more than a cosmetic loss: an INVALID_ARGUMENT that
retry middleware would have left alone becomes an unclassified
failure that gets retried through the whole backoff schedule.
Branch with errors.Is
Section titled “Branch with errors.Is”Match on sentinels, never on message text.
switch {case errors.Is(err, ErrRecipeNotFound): // This exact failure: improvise a recipe instead.case errors.Is(err, status.ErrNotFound): // Any not-found, including ai.ErrModelNotFound.case errors.Is(err, ai.ErrMaxTurnsExceeded): // The tool loop hit its limit; raise it with ai.WithMaxTurns.case errors.Is(err, status.ErrResourceExhausted): // Rate limited or out of quota: back off and try again.}The framework packages ship sentinels for the failures they raise, each a subtype of a base sentinel.
From ai, for generation:
| Sentinel | Base | Raised when |
|---|---|---|
ErrModelNotFound | status.ErrNotFound | The named model is not registered. Usually the providing plugin is missing from genkit.Init. |
ErrToolNotFound | status.ErrNotFound | The model called a tool that is on neither the request nor the registry. |
ErrToolFailed | status.ErrInternal | A tool returned an error, panicked, or produced output that did not match its declared schema. The loop’s partial response rides alongside it. |
ErrMaxTurnsExceeded | status.ErrAborted | The tool loop hit its turn limit before the model produced a final response. Raise the limit with ai.WithMaxTurns, or continue from the partial response’s History(). |
ErrBudgetExceeded | status.ErrAborted | Middleware that enforces a usage budget stopped the run. Like the turn limit, it is a limit the caller set, so the partial response reports ai.FinishReasonAborted. |
ErrUnsupportedByModel | status.ErrInvalidArgument | The request used a capability the model does not advertise: media, tools, tool choice, a system role. |
ErrInvalidPart | status.ErrInvalidArgument | A Part is malformed for the operation: the wrong kind, missing a required field, or carrying a field its kind does not allow. |
ErrInputTypeMismatch | status.ErrInvalidArgument | A prompt’s input could not be interpreted as the type a content function declared, so the function never ran. |
ErrUnresolvedToolRequest | status.ErrInvalidArgument | A resumed generation left an interrupted tool request without a Respond or Restart directive. |
ErrGenerationBlocked | status.ErrFailedPrecondition | The provider refused to generate, usually a safety filter. Only the typed helpers report it; ai.Generate hands the response back so you can read FinishReason. |
ErrToolFailed names the failing tool in its message (tool "getWeather" failed: ...)
and wraps the tool’s own error with %w, so errors.Is and errors.As still reach it.
There is no structured tool-name field. To tell one tool’s failure from another’s,
define a sentinel inside the tool and branch on that rather than on ErrToolFailed.
A tool error that the model can fix, such as invalid input or a missing record,
does not have to stop the loop. Return it through tool.Fail from
github.com/firebase/genkit/go/ai/tool, and the loop answers the call with the
error text and lets the model try again; see
Return an error to the model.
Generation errors carry the partial response
Section titled “Generation errors carry the partial response”Once a generate request has resolved, an error arrives beside the partial
*ai.ModelResponse rather than a nil one. The response reports
ai.FinishReasonFailed when something broke and ai.FinishReasonAborted when
the caller stopped the loop, carries the same failure classified in
resp.Error, and its History() ends at the last completed tool round, so a
caller can send it again without repeating work. Errors raised before the
request was sent, such as ErrModelNotFound, still come with a nil response.
See Failed and stopped generations.
From core/status, for the action machinery:
| Sentinel | Base | Raised when |
|---|---|---|
ErrInvalidSchema | status.ErrInvalidArgument | A declared input or output schema could not be resolved or compiled. The schema is wrong, not the value, so a retry will not help; fix the Go type or the schema. |
ErrInvalidInput | status.ErrInvalidArgument | A value failed validation against an action’s input schema, for example a model producing malformed tool arguments. |
ErrInvalidOutput | status.ErrInternal | An action or model produced a value that does not match the declared output schema: unparseable JSON, an enum reply outside the set, an action output failing validation. |
ErrActionNotFound | status.ErrNotFound | No action is registered under the requested key. |
ErrPanic | status.ErrInternal | The framework recovered a panic at an action boundary that recovers: a bidirectional action or the agent runtime. See Panics. |
ErrInvalidOutput is the one to branch on when a model’s structured output is
unusable and the generation is worth retrying:
recipe, resp, err := genkit.GenerateData[Recipe](ctx, g, ai.WithPrompt("Suggest a recipe."))if errors.Is(err, status.ErrInvalidOutput) { // The model answered, but not in the shape we asked for. resp.Text() // holds what it wrote, so the retry can show it what to fix.}One gap: ModelResponse.Output(v) on a response with no format handler falls back to
a plain json.Unmarshal, whose error carries no sentinel. Request structured output
through ai.WithOutputType or genkit.GenerateData and you get the classified error.
From core, for bidirectional actions:
| Sentinel | Base | Raised when |
|---|---|---|
ErrConnectionClosed | status.ErrFailedPrecondition | Send on a connection whose input side was closed with BidiConnection.Close. |
ErrActionCompleted | status.ErrFailedPrecondition | Send on a connection whose action already returned. Its result is available from BidiConnection.Output. |
Three functions inspect an error without unwrapping it by hand. Together they are
everything a transport needs (logger here is github.com/firebase/genkit/go/core/logger):
// PublicMessage returns the error's own message when it is public, and a// generic string derived from the status otherwise.msg, public := status.PublicMessage(err)if !public { logger.Error(ctx, "request failed", "error", err)}
// Of picks the response code, whether or not the message was public.http.Error(w, msg, status.Of(err).HTTPCode())
// Classified answers the stronger question: did anything in the chain// actually classify this, or is INTERNAL only the fallback?if s, ok := status.Classified(err); ok && s == status.Unavailable { // A failure the provider told us to retry.}status.Of reports the status of the outermost status.Error in the chain, so a
deliberate reclassification at a boundary wins. It maps a cancelled context to
CANCELLED, an expired one to DEADLINE_EXCEEDED, and anything unclassified to
INTERNAL. status.Classified returns the same status plus whether anything in the
chain really carried one. That second bit is what middleware needs, so an unclassified
failure is not mistaken for a deliberate INTERNAL.
Errors that crossed a wire
Section titled “Errors that crossed a wire”A *status.Error decoded from JSON carries its status but not the sentinel that
built it. That is the error in an agent’s AgentOutput.Error, in the Error of a
snapshot read back from a session store, in a remote agent’s failure, and in
resp.Error on a model response that travelled as data. Such an error matches the base sentinel of its
status, and no sentinel derived from it, because the wire does not say which one
classified it:
var decoded status.Errorif err := json.Unmarshal([]byte(`{"status":"NOT_FOUND","message":"no such model"}`), &decoded); err != nil { return err}
errors.Is(&decoded, status.ErrNotFound) // true: the base sentinel of NOT_FOUNDerrors.Is(&decoded, ai.ErrModelNotFound) // false: the domain sentinel did not travelBranch on base sentinels for anything that can come from another process, and keep domain sentinels for errors raised in your own.
Which provider errors arrive classified
Section titled “Which provider errors arrive classified”The first-party model plugins classify provider HTTP failures into canonical
statuses, so a 429 reaches you as status.ErrResourceExhausted rather than as an
opaque SDK error: googlegenai, compat_oai and the providers built on it, and the
Anthropic plugins all do this. googlegenai also records the delay the service asked
for, readable with googlegenai.RetryDelay(err).
The same wrapping covers embedders. An input longer than the embedder’s token limit
comes back as HTTP 400, so errors.Is(err, status.ErrInvalidArgument). Batching is
handled for you (100 inputs per call on the Gemini API, up to 250 on the Gemini Enterprise API), so an
invalid-argument failure from an embed call points at one oversized document, not at
the batch size.
A plugin that does not classify leaves its errors unclassified, and an unclassified
error reports INTERNAL. Check which you have with status.Classified(err): the
second result is false when nothing in the chain carried a status.
Panics
Section titled “Panics”Genkit does not recover panics at the ordinary action boundary. A panic in a flow or
in model middleware unwinds normally; under net/http the connection is dropped with
no response body.
Tool calls are the exception, because each one runs on its own goroutine, where an
unrecovered panic would end the process. A tool, or a WrapTool hook, that panics
fails its call with the fixed message tool panicked, so the loop reports
ai.ErrToolFailed as for any other tool error. The panic value can hold anything
the tool had in hand, so it and the stack go to the error log only, never to the
model or the returned error.
status.ErrPanic is raised where the framework recovers at an action boundary:
bidirectional actions and the experimental agent runtime, which turn the recovered
value into a classified INTERNAL error such as panic in bidi action "name": ....
If you want a panic in your own code to reach a client as a status, recover it yourself and return a classified error, or wrap your mux in a recovery middleware.
The status vocabulary
Section titled “The status vocabulary”status.Name is the wire status. Each error status has a matching base sentinel named
Err plus the name, so status.InvalidArgument pairs with status.ErrInvalidArgument.
The ones you will reach for most:
| Name | Base sentinel | HTTP |
|---|---|---|
status.InvalidArgument | status.ErrInvalidArgument | 400 |
status.Unauthenticated | status.ErrUnauthenticated | 401 |
status.PermissionDenied | status.ErrPermissionDenied | 403 |
status.NotFound | status.ErrNotFound | 404 |
status.ResourceExhausted | status.ErrResourceExhausted | 429 |
status.Unavailable | status.ErrUnavailable | 503 |
status.Internal | status.ErrInternal | 500 |
The package declares seventeen names in total, following the
Google API error model; see the
core/status reference
for the full set with its gRPC codes and HTTP mappings. When you only know the status
at run time, status.Base(name) returns its base sentinel.
At the HTTP boundary
Section titled “At the HTTP boundary”genkit.Handler derives the whole response from the classification, so the code and
the message can never disagree:
- The response code is
status.Of(err).HTTPCode(), always. - The body is JSON,
{"status": ..., "message": ...}, with theapplication/jsoncontent type.statusis the status name, so a client can tell apart statuses that share an HTTP code, such asINVALID_ARGUMENTandFAILED_PRECONDITION. messageisstatus.PublicMessage(err): the message verbatim when the error was built withstatus.PublicErrorf, otherwise a generic string derived from the status.- The full error is logged server-side either way, which is the only complete record.
A success body is {"result": ...}. This is the same error body a JavaScript Genkit
server sends.
| What the flow returned | Code | Body |
|---|---|---|
errors.New("connecting to db at 10.0.0.3 as admin: password rejected") | 500 | {"status":"INTERNAL","message":"internal"} |
status.Errorf(status.ErrInvalidArgument, "dish %q is not on the menu", dish) | 400 | {"status":"INVALID_ARGUMENT","message":"invalid argument"} |
status.PublicErrorf(status.ErrInvalidArgument, "dish must not be empty") | 400 | {"status":"INVALID_ARGUMENT","message":"dish must not be empty"} |
genkit.DefineFlow(g, "cookbookFlow", func(ctx context.Context, input CookbookRequest) (string, error) { if strings.TrimSpace(input.Dish) == "" { // 400, body: dish must not be empty return "", status.PublicErrorf(status.ErrInvalidArgument, "dish must not be empty") } // 404, body: no recipe for "lasagna" in the cookbook return lookupRecipe(input.Dish)})
genkit.DefineFlow(g, "leakyFlow", func(ctx context.Context, _ any) (string, error) { // 500, body: internal. The real text is logged server-side only. return "", errors.New("connecting to db at 10.0.0.3 as admin: password rejected")})
mux := http.NewServeMux()for _, a := range genkit.ListFlows(g) { mux.HandleFunc("POST /"+a.Name(), genkit.Handler(a))}Served agents
Section titled “Served agents”An agent served with genkit.Handler applies the same rule to the errors inside its
results. A failed turn’s AgentOutput.Error, and the snapshot error that
getSnapshot and waitForSnapshot return, go out with the generic message for their
status and no details unless the error was built with status.PublicErrorf. Errors
about the caller’s own input, such as an invalid message or a snapshot from another
session, are public, so a remote caller still learns what it sent wrong. The session
store and in-process callers keep the full text, and so does the Dev UI under
GENKIT_ENV=dev. Only genkit.Handler redacts: an agent you run from a handler of your
own returns its errors unchanged. See Agents over HTTP.
Custom error bodies
Section titled “Custom error bodies”genkit.Handler always writes the {"status", "message"} body. To return another
shape, mount genkit.HandlerFunc instead: it runs the action and hands the error back
rather than writing a response, so you render the body.
func errorJSON(h func(http.ResponseWriter, *http.Request) error) http.HandlerFunc { return func(w http.ResponseWriter, r *http.Request) { err := h(w, r) if err == nil { return }
// Only a PublicErrorf message is safe to echo. Anything else gets the // generic string PublicMessage derives from the status. msg, public := status.PublicMessage(err) if !public { logger.Error(r.Context(), "flow failed", "error", err) }
// status.Name is a string type, so it encodes as "INVALID_ARGUMENT". body := map[string]any{"status": status.Of(err), "message": msg}
// Classified reports whether anything in the chain really carried a // status, so an unclassified failure is not read as a deliberate INTERNAL. if _, ok := status.Classified(err); !ok { body["classified"] = false }
w.Header().Set("Content-Type", "application/json") w.WriteHeader(status.Of(err).HTTPCode()) _ = json.NewEncoder(w).Encode(map[string]any{"error": body}) }}
mux.Handle("POST /cookbookFlow", errorJSON(genkit.HandlerFunc(flow)))Write the response before the handler streams, or not at all: on a streaming request the headers are already sent, and a failure has to arrive in the body as described in Errors on a streaming request.
The redaction is environment-gated. With GENKIT_ENV=dev the real err.Error() text
is returned instead of the generic string, so the developer causing the failure can
see it. The response code is the same either way, and a PublicErrorf response is
byte for byte the same either way, since its message already escapes. GENKIT_ENV is
read per request and defaults to production when unset, so treat what you see locally
as a debugging aid and never as the contract your clients get.
Errors on a streaming request
Section titled “Errors on a streaming request”A streaming request has already answered 200 with a text/event-stream content type
before the flow runs, so a failure cannot change the status line. It arrives as a
final event in the body instead, after whatever chunks were already sent, and like
every event it is terminated by a blank line:
data: {"error":{"status":"INVALID_ARGUMENT","message":"dish must not be empty"}}The frame carries exactly two fields, status and message. There is no details
field, and redaction works the same as on the non-streaming path, so an unclassified
failure arrives as {"error":{"status":"INTERNAL","message":"internal"}} and the full
error reaches the server log only. A client has to read the body to notice a streaming
failure, because the HTTP status is 200 either way.