Error Handling & Exceptions

Last updated: March 23, 2026

When interacting with the Chrome Built-in AI APIs, various exceptions may be thrown depending on hardware constraints, network conditions, or invalid inputs. Understanding these errors is crucial for building resilient AI applications that gracefully degrade or guide the user.

Error	JS Type	Description	Resolution
`QuotaExceededError` Context Window Overflow	`DOMException`	Thrown when the input is too large and the combination of your system prompt, context, and input exceeds the maximum token limit. Props: `e.requested`: Total input tokens. `e.quota`: Tokens available.	Catch the error and inform the user that their input is too large. Use `measureInputUsage()` beforehand to truncate inputs proactively if needed.
`NotReadableError` Safety Filtered	`DOMException`	Thrown when the execution yielded an unsafe response. The built-in safety model intercepted the output due to toxicity or restricted topics.	Inform the user that the response violated safety guidelines and could not be displayed. Consider adjusting the system prompt to guide safer responses.
`NotAllowedError` Permission Denied	`DOMException`	Thrown when a user permission error occurs (e.g., the user is not allowed to execute the model), or if an Enterprise Policy disables the feature.	Display a message indicating that the browser environment or administrator policy prohibits the use of local AI models. Handle the missing capability gracefully in your UI.
`NotSupportedError` Unsupported Config	`DOMException`	Thrown when: 1. The request is invalid (input/options could not be processed). 2. The model attempted to output in an untested language. 3. The model attempted to output low quality text. 4. The response constraint JSON schema is not supported.	Adjust your constraints or handle the unsupported state gracefully. Ensure you use the `availability(options)` check to verify base support before calling `create()`.
`InvalidStateError` State Destroyed	`DOMException`	Thrown when the model execution session has been explicitly destroyed, the document is no longer active, or the execution context is invalid.	Ensure you are not calling `prompt()` on a session that has already been destroyed, and that the calling window context is still alive.
`OperationError` Service Unavailable	`DOMException`	Thrown when the underlying model execution service (the Chrome process managing the model) is not available or has crashed.	Treat this as a fatal crash of the local model and inform the user that the service is currently unavailable.
`UnknownError` Generic Failure	`DOMException`	Thrown when other generic, unclassified failures occur, or when an internal state like a "retryable" or "non-retryable" engine error is encountered.	Capture and log the error for telemetry and display a graceful failure message.
`NetworkError` Download Failure	`DOMException`	Thrown during `create()` if a required model or language pack needs to be downloaded but the network request fails.	Catch the error, prompt the user to check their internet connection, and provide a button to retry the initialization.
`AbortError` Operation Cancelled	`DOMException`	Thrown when an operation is cancelled by the developer via an `AbortSignal`, the response was disabled, or the request was cancelled internally by Chrome.	This is usually an expected state if your UI allows users to "Stop Generation". Catch it and silently reset your UI state to idle.
`SyntaxError` Invalid Structure	`DOMException`	Thrown when the model fails to generate a response that perfectly matches a strict `responseConstraint` (JSON Schema/RegExp), or if `prefix: true` is misused.	Simplify your constraint rules, or provide better system instructions so the model understands exactly what format is required.
`SecurityError` Cross-Origin Media	`DOMException`	Thrown for cross-origin media violations in multimodal inputs — for example a canvas tainted by cross-origin content.	Ensure media has `crossorigin="anonymous"` or is same-origin so the source is not tainted.
`EncodingError` Undecodable Media	`DOMException`	Thrown when raw media bytes passed as multimodal input cannot be decoded using standard browser sniffing rules.	Only pass media in formats the browser can decode (e.g. JPEG, PNG, WebP for images).
`TypeError` Validation Errors	`JS Native`	Thrown for invalid option combinations — for example an `initialPrompts` array where the `system` role is not at index 0.	Review your configuration code against the API specifications to ensure you are passing valid parameters.
`RangeError` Out-of-Bounds Params	`JS Native`	Thrown when model parameters (e.g. `temperature`, `topK`) are set outside their allowed bounds.	Keep parameter values within the ranges documented for the API.

PreviousAborting Operations Next Prompt API