hasura/graphql-engine · error · ErrorResponse

SQLite Agent: Uncaught Exception

Error message

SQLite Agent: Uncaught Exception

What it means

This is the SQLite Agent's top-level Fastify error handler: any uncaught exception thrown while handling an HTTP request in the agent results in this generic 500 response containing the underlying error's name and message. It is not a specific error itself but a catch-all that surfaces the root cause of request-processing failures (query building, schema parsing, SQLite execution, etc.).

Source

Thrown at dc-agents/sqlite/src/index.ts:96

  this.log.error(error);

  if (isErrorWithStatusCode(error)) {
    const errorResponse: ErrorResponse = {
      type: error.type,
      message: error.message,
      details: error.details,
    };
    reply.status(error.code).send(errorResponse);
  } else {
    const errorResponse: ErrorResponse = {
      type: 'uncaught-error',
      message: 'SQLite Agent: Uncaught Exception',
      details: {
        name: (error as Error).name,
        message: (error as Error).message,
      },
    };
    reply.status(500).send(errorResponse);
  }
});

if (METRICS) {
  // See: https://www.npmjs.com/package/fastify-metrics
  server.register(metrics, {
    endpoint: '/metrics',
    routeMetrics: {
      enabled: true,
      registeredRoutesOnly: false,
    },
  });
}

if (PERMISSIVE_CORS) {
  // See: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin
  server.register(FastifyCors, {
    origin: true,

View on GitHub (pinned to 724551b9ae)

Solutions

1. Read the `details.name` and `details.message` fields in the 500 response — they carry the original exception and pinpoint the real failure
2. Reproduce the failing request body locally against the agent with logging enabled to get a stack trace
3. If the root cause is an unsupported query feature (e.g. UDF targets), fix the client request; if it's a parser/DDL issue, simplify or fix the schema
4. File an issue with the request payload and stack trace if it's an internal bug in the agent

Example fix

// before: sending a target of type 'function'
await agent.query({ target: { type: 'function', name: 'my_udf' }, ... });
// after: only query tables or interpolated targets
await agent.query({ target: { type: 'table', name: ['album'] }, ... });

null

null

// Wrap agent calls; inspect the generic 500 for root cause
try {
  const res = await fetch(`${agentUrl}/query`, {...});
  if (!res.ok) {
    const err = await res.json();
    // err.details.name / err.details.message hold the original exception
    log.error({ cause: err.details }, 'sqlite agent failure');
    throw new Error(err.details?.message ?? 'agent error');
  }
} catch (e) { /* surface to caller with context */ }

When it happens

Trigger: Any GET/POST route handler (query, explain, schema endpoints) throwing a non-ErrorWithStatusCode exception, e.g. a bug in query generation, sqlite-parser returning an unexpected AST shape, or a broken DB connection during request handling.

Common situations: Deploying the SQLite agent against a database whose DDL the parser cannot handle; sending malformed request bodies that bypass validation; runtime bugs in query.ts/schema.ts that throw plain Error objects instead of ErrorWithStatusCode.

Related errors

• User defined functions not supported in queries
• Can't execute table_query for UDFs
• ${tableName.join('.')} is not a valid table
• `escapeTargetName` only implemented for tables and interpola
• Couldn't find relationship ${field.relationship} for field $

AI-assisted analysis of hasura/graphql-engine@724551b9ae (2026-08-28). Data as JSON: /api/errors/d0fbf59781facdee. Report an issue: GitHub.