{"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":197,"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":179,"sourceCodeEnd":215,"githubUrl":"https://github.com/tursodatabase/turso/blob/bad083fafbefdeae9a42ec19bdaaad8918dcf411/serverless/javascript/src/session.ts#L179-L215","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Fix the SQL: run the exact statement in the CLI (scripts/diff.sh or turso) to see the full server error","Log err.code together with the message (error.code carries e.g. SQLITE_ERROR) to classify the failure","If only the fallback text appears with no useful message, capture the raw HTTP response and report the server issue — the response is malformed"],"exampleFix":"// before\nconst stmt = await db.prepare(\"SELEC * FROM users\"); // describe fails server-side\n\n// after\nconst stmt = await db.prepare(\"SELECT * FROM users\");","handlingStrategy":"try-catch","validationCode":null,"typeGuard":"const isDatabaseError = (e: unknown): e is Error & { code?: string } =>\n  e instanceof Error && e.name === \"DatabaseError\";","tryCatchPattern":"try {\n  const stmt = await db.prepare(sql);\n} catch (e) {\n  if (e instanceof Error && e.name === \"DatabaseError\") {\n    console.error(\"prepare failed:\", (e as { code?: string }).code, e.message, \"SQL:\", sql);\n    // the server message (when present) names the syntax error — fix the SQL\n  }\n  throw e;\n}","preventionTips":["Keep SQL in constants or template functions and validate them with prepare() at startup","Remember prepare() is a server round trip here — server-side SQL errors surface at prepare time, not execution","Run new statements through the CLI before shipping them"],"tags":["sql","prepare","protocol","javascript"],"backgroundTag":"sql-prepare-error","analyzedSha":"bad083fafbefdeae9a42ec19bdaaad8918dcf411","analyzedAt":"2026-08-16T23:12:11.798Z","schemaVersion":2},"datasetVersion":"2026-08-17T04:17:16.089Z"}