From 5329290919e026da8c288d6cb4f50161347c8f0d Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Tue, 6 Jan 2026 15:33:53 +0000 Subject: [PATCH 1/2] docs: add SqlError class documentation for SQL error handling MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add documentation for the new SqlError class that is thrown when SQL queries fail in Agents. This helps developers understand how to handle SQL-specific errors through the onError method. Related to cloudflare/agents#768 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 --- .../docs/agents/api-reference/agents-api.mdx | 51 +++++++++++++++++++ 1 file changed, 51 insertions(+) diff --git a/src/content/docs/agents/api-reference/agents-api.mdx b/src/content/docs/agents/api-reference/agents-api.mdx index 4b2ac2b04ec19b8..46fc25a13ae86f9 100644 --- a/src/content/docs/agents/api-reference/agents-api.mdx +++ b/src/content/docs/agents/api-reference/agents-api.mdx @@ -596,6 +596,57 @@ Visit the [state management API documentation](/agents/api-reference/store-and-s ::: +#### SQL error handling + +When a SQL query fails, the Agents SDK throws a `SqlError` that is passed to your `onError` method. The `SqlError` class provides access to the failed query, making it easier to debug and handle SQL-specific errors. + +```ts +// Error class for SQL execution failures +class SqlError extends Error { + // The SQL query that failed + readonly query: string; + + constructor(query: string, cause: unknown); +} +``` + + + +```ts +export class YourAgent extends Agent { + // Override onError to handle SQL errors + onError(error: unknown): Error { + // Check if the error is a SQL error + if (error instanceof SqlError) { + console.error(`SQL query failed: ${error.query}`); + console.error(`Error details:`, error.cause); + + // You can handle specific SQL errors differently + return new Error(`Database operation failed: ${error.message}`); + } + + // Handle other errors + return error instanceof Error ? error : new Error(String(error)); + } + + async getUserData(userId: string) { + // SQL errors are automatically caught and passed to onError + const users = this.sql` + SELECT * FROM users WHERE id = ${userId} + `; + return users[0]; + } +} +``` + + + +The `SqlError` class includes: + +- `query`: The SQL query string that failed +- `cause`: The underlying error that caused the SQL query to fail +- `message`: A formatted error message combining the cause + ### MCP Client API The Agents SDK allows your Agent to act as an MCP (Model Context Protocol) client, connecting to remote MCP servers and using their tools, resources, and prompts. From 51799b9e56256db4168f4e76f968ea02f2ce4935 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" Date: Tue, 6 Jan 2026 17:03:54 +0000 Subject: [PATCH 2/2] docs(agents): document SqlError class for SQL error handling MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Document the new SqlError class that wraps SQL query failures. Users can now distinguish SQL errors in their onError handler and access the failed query via the query property. Synced from cloudflare/agents PR #768 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Sonnet 4.5 --- .../docs/agents/api-reference/agents-api.mdx | 49 +++++++++++++++++++ .../api-reference/store-and-sync-state.mdx | 2 + .../docs/agents/concepts/agent-class.mdx | 14 +++++- 3 files changed, 63 insertions(+), 2 deletions(-) diff --git a/src/content/docs/agents/api-reference/agents-api.mdx b/src/content/docs/agents/api-reference/agents-api.mdx index 46fc25a13ae86f9..eb5cdb09c2a1581 100644 --- a/src/content/docs/agents/api-reference/agents-api.mdx +++ b/src/content/docs/agents/api-reference/agents-api.mdx @@ -536,6 +536,55 @@ class Agent { } ``` +#### SQL error handling + +When a SQL query fails, the error is wrapped in a `SqlError` and passed to your Agent's [`onError` method](/agents/api-reference/agents-api/#websocket-api). The `SqlError` class provides access to the failed query, making it easier to debug and handle SQL-related errors. + +```ts +// Error class for SQL execution failures +class SqlError extends Error { + // The SQL query that failed + readonly query: string; + + constructor(query: string, cause: unknown); +} +``` + +You can handle SQL errors specifically in your `onError` method by checking if the error is an instance of `SqlError`: + + + +```ts +import { Agent, SqlError } from "agents"; + +export class YourAgent extends Agent { + // Handle SQL errors specifically + async onError(connection: Connection | unknown, error?: unknown) { + const err = error || connection; + + if (err instanceof SqlError) { + // SQL-specific error handling + console.error("SQL query failed:", err.query); + console.error("Error:", err.message); + // Optionally access the original cause + console.error("Cause:", err.cause); + } else { + // Handle other errors + console.error("Error:", err); + } + + throw err; + } + + async someMethod() { + // SQL errors are automatically caught and passed to onError + const users = this.sql`SELECT * FROM users WHERE invalid_syntax`; + } +} +``` + + + ```ts diff --git a/src/content/docs/agents/api-reference/store-and-sync-state.mdx b/src/content/docs/agents/api-reference/store-and-sync-state.mdx index 8943e4295dc893c..1c8f5800de3179d 100644 --- a/src/content/docs/agents/api-reference/store-and-sync-state.mdx +++ b/src/content/docs/agents/api-reference/store-and-sync-state.mdx @@ -229,6 +229,8 @@ Learn more about the zero-latency SQL storage that powers both Agents and Durabl The SQL API exposed to an Agent is similar to the one [within Durable Objects](/durable-objects/api/sqlite-storage-api/#sql-api): Durable Object SQL methods available on `this.ctx.storage.sql`. You can use the same SQL queries with the Agent's database, create tables, and query data, just as you would with Durable Objects or [D1](/d1/). +When a SQL query fails, the error is automatically wrapped in a `SqlError` class and passed to your Agent's `onError` method. The `SqlError` class includes the `query` property, allowing you to inspect which SQL query failed. Refer to the [SQL error handling documentation](/agents/api-reference/agents-api/#sql-error-handling) to learn more about handling SQL errors. + ### Use Agent state as model context You can combine the state and SQL APIs in your Agent with its ability to [call AI models](/agents/api-reference/using-ai-models/) to include historical context within your prompts to a model. Modern Large Language Models (LLMs) often have very large context windows (up to millions of tokens), which allows you to pull relevant context into your prompt directly. diff --git a/src/content/docs/agents/concepts/agent-class.mdx b/src/content/docs/agents/concepts/agent-class.mdx index 86f130d5f478f3d..7330f5d17aeeb5c 100644 --- a/src/content/docs/agents/concepts/agent-class.mdx +++ b/src/content/docs/agents/concepts/agent-class.mdx @@ -411,10 +411,20 @@ function someUtilityFunction() { `Agent` extends `Server`'s `onError` so it can be used to handle errors that are not necessarily WebSocket errors. It is called with a `Connection` or `unknown` error. +When SQL queries fail, the error is wrapped in a `SqlError` class and passed to this method, allowing you to distinguish SQL errors from other error types and access the failed query. + ```ts +import { Agent, SqlError } from "agents"; + class MyAgent extends Agent { onError(connectionOrError: Connection | unknown, error?: unknown) { - if (error) { + const err = error || connectionOrError; + + if (err instanceof SqlError) { + // SQL query error - access the failed query + console.error("SQL query failed:", err.query); + console.error("Error:", err.message); + } else if (error) { // WebSocket connection error console.error("Connection error:", error); } else { @@ -423,7 +433,7 @@ class MyAgent extends Agent { } // Optionally throw to propagate the error - throw connectionOrError; + throw err; } } ```