tursodatabase/turso · error · DatabaseError

Describe execution failed

Error message

Describe execution failed

What it means

session.describe(sql) received an error-typed result from the server for its describe request. The literal 'Describe execution failed' is only the fallback used when the server's error object carries no message; normally the thrown DatabaseError carries the server's own message and code. It signals the server could not analyze the statement, not a transport failure.

Solutions

1. Run the same SQL through session.execute() to get the fuller server error message and code
2. Fix the SQL syntax or the missing table/column reference
3. Wrap dynamic describe() calls in try/catch and log result.error.code when present

Example fix

// before
const desc = await session.describe(`SELECT no_such_col FROM users`);

// after
const desc = await session.describe(`SELECT id, name FROM users`);

import { DatabaseError } from '@tursodatabase/serverless';

function isDescribeError(e: unknown): e is DatabaseError {
  return e instanceof DatabaseError && e.message === 'Describe execution failed';
}

try {
  return await session.describe(sql);
} catch (e) {
  if (e instanceof DatabaseError) {
    // prefer execute() to get the full server message for the same statement
    console.error('describe failed:', e.code, e.message);
  }
  throw e;
}

When it happens

Trigger: Calling describe() on syntactically invalid SQL; describing a statement that references a nonexistent table or column; describing statement forms the server cannot analyze. On failure the session also resets baton and autocommit state.

Common situations: Dynamically built SQL that turned out malformed; describing a query against a table not yet created in a migration; a typo in column names discovered at prepare/describe time.

Related errors

• Batch execution failed
• Sequence execution failed
• SQL execution failed
• SQL execution failed
• batch statement failed: is not allowed in an atomic batch

AI-assisted analysis of tursodatabase/turso@c1e5928725 (2026-08-20). Data as JSON: /api/errors/9ffc84984b408842. Report an issue: GitHub.

Appendix: source

Thrown at serverless/javascript/src/session.ts:239

    try {
      response = await executePipeline(this.httpContext(queryOptions), request, this.createAbortSignal(queryOptions));
    } catch (e) {
      this.baton = null;
      this.autocommit = true;
      throw e;
    }

    this.baton = response.baton;
    if (response.base_url) {
      this.baseUrl = normalizeUrl(response.base_url);
    }
    this.updateAutocommit(response);

    // Check for errors in the response
    if (response.results && response.results[0]) {
      const result = response.results[0];
      if (result.type === "error") {
        throw new DatabaseError(result.error?.message || 'Describe execution failed', result.error?.code);
      }

      if (result.response?.type === "describe" && result.response.result) {
        return result.response.result as DescribeResult;
      }
    }

    throw new DatabaseError('Unexpected describe response');
  }

  /**
   * Execute a SQL statement and return all results.
   *
   * @param sql - The SQL statement to execute
   * @param args - Optional array of parameter values or object with named parameters
   * @param safeIntegers - Whether to return integers as BigInt
   * @returns Promise resolving to the complete result set
   */

View on GitHub (pinned to c1e5928725)