tursodatabase/turso · error · DatabaseError

Describe execution failed

Error message

Describe execution failed

What it means

DatabaseError thrown when the server returns an error result for the describe request that Connection.prepare() (and Transaction.prepare()) sends to fetch column metadata. The server's own message — typically a SQL parse error — is used when present; the literal 'Describe execution failed' text only appears when the server's error entry omits error.message, which usually indicates a server-side anomaly.

Source

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

    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 bad083fafb)

Solutions

1. Fix the SQL: run the exact statement in the CLI (scripts/diff.sh or turso) to see the full server error
2. Log err.code together with the message (error.code carries e.g. SQLITE_ERROR) to classify the failure
3. If only the fallback text appears with no useful message, capture the raw HTTP response and report the server issue — the response is malformed

Example fix

// before
const stmt = await db.prepare("SELEC * FROM users"); // describe fails server-side

// after
const stmt = await db.prepare("SELECT * FROM users");

const isDatabaseError = (e: unknown): e is Error & { code?: string } =>
  e instanceof Error && e.name === "DatabaseError";

try {
  const stmt = await db.prepare(sql);
} catch (e) {
  if (e instanceof Error && e.name === "DatabaseError") {
    console.error("prepare failed:", (e as { code?: string }).code, e.message, "SQL:", sql);
    // the server message (when present) names the syntax error — fix the SQL
  }
  throw e;
}

When it happens

Trigger: await client.prepare('SELEC * FROM t') — malformed SQL rejected at describe time; describing SQL referencing objects the server cannot resolve; server error entries lacking a message field, which trigger the fallback wording.

Common situations: Typos in SQL caught at prepare instead of execution; dynamically assembled SQL with missing clauses; developers assuming prepare() is client-side — here it round-trips to the server, so server-side SQL errors surface at prepare.

Related errors

• SQL execution failed
• The supplied SQL string contains no statements
• Unexpected describe response
• Batch execution failed
• Sequence execution failed

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