{"record":{"id":"9ffc84984b408842","repo":"tursodatabase/turso","slug":"describe-execution-failed","errorCode":null,"errorMessage":"Describe execution failed","messagePattern":"Describe execution failed","errorType":"exception","errorClass":"DatabaseError","httpStatus":null,"severity":"error","filePath":"serverless/javascript/src/session.ts","lineNumber":239,"sourceCode":"    try {\n      response = await executePipeline(this.httpContext(queryOptions), request, this.createAbortSignal(queryOptions));\n    } catch (e) {\n      this.baton = null;\n      this.autocommit = true;\n      throw e;\n    }\n\n    this.baton = response.baton;\n    if (response.base_url) {\n      this.baseUrl = normalizeUrl(response.base_url);\n    }\n    this.updateAutocommit(response);\n\n    // Check for errors in the response\n    if (response.results && response.results[0]) {\n      const result = response.results[0];\n      if (result.type === \"error\") {\n        throw new DatabaseError(result.error?.message || 'Describe execution failed', result.error?.code);\n      }\n\n      if (result.response?.type === \"describe\" && result.response.result) {\n        return result.response.result as DescribeResult;\n      }\n    }\n\n    throw new DatabaseError('Unexpected describe response');\n  }\n\n  /**\n   * Execute a SQL statement and return all results.\n   *\n   * @param sql - The SQL statement to execute\n   * @param args - Optional array of parameter values or object with named parameters\n   * @param safeIntegers - Whether to return integers as BigInt\n   * @returns Promise resolving to the complete result set\n   */","sourceCodeStart":221,"sourceCodeEnd":257,"githubUrl":"https://github.com/tursodatabase/turso/blob/c1e59287258d99b309e362a63f48822256e2f65f/serverless/javascript/src/session.ts#L221-L257","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Run the same SQL through session.execute() to get the fuller server error message and code","Fix the SQL syntax or the missing table/column reference","Wrap dynamic describe() calls in try/catch and log result.error.code when present"],"exampleFix":"// before\nconst desc = await session.describe(`SELECT no_such_col FROM users`);\n\n// after\nconst desc = await session.describe(`SELECT id, name FROM users`);","handlingStrategy":"try-catch","validationCode":null,"typeGuard":"import { DatabaseError } from '@tursodatabase/serverless';\n\nfunction isDescribeError(e: unknown): e is DatabaseError {\n  return e instanceof DatabaseError && e.message === 'Describe execution failed';\n}","tryCatchPattern":"try {\n  return await session.describe(sql);\n} catch (e) {\n  if (e instanceof DatabaseError) {\n    // prefer execute() to get the full server message for the same statement\n    console.error('describe failed:', e.code, e.message);\n  }\n  throw e;\n}","preventionTips":["Validate generated SQL with a linter/parser before describe() when SQL is built dynamically","Only describe() statements against schema versions you know exist (post-migration)","Prefer execute() during development for richer error detail, switch to describe() for metadata only"],"tags":["sql","describe","typescript"],"backgroundTag":"sql-execution-error","analyzedSha":"c1e59287258d99b309e362a63f48822256e2f65f","analyzedAt":"2026-08-20T07:02:18.389Z","contentChangedAt":"2026-08-20T07:02:18.389Z","schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}