{"record":{"id":"f0a95927e04ba2e1","repo":"tursodatabase/turso","slug":"unexpected-describe-response","errorCode":null,"errorMessage":"Unexpected describe response","messagePattern":"Unexpected describe response","errorType":"exception","errorClass":"DatabaseError","httpStatus":null,"severity":"error","filePath":"serverless/javascript/src/session.ts","lineNumber":205,"sourceCode":"    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   */\n  async execute(sql: string, args: any[] | Record<string, any> = [], safeIntegers: boolean = false, queryOptions?: QueryOptions): Promise<any> {\n    const { response, entries } = await this.executeRaw(sql, args, queryOptions);\n    const result = await this.processCursorEntries(entries, safeIntegers);\n    return result;\n  }\n\n  /**\n   * A trailing batch step gated on `is_autocommit`, appended to every cursor","sourceCodeStart":187,"sourceCodeEnd":223,"githubUrl":"https://github.com/tursodatabase/turso/blob/bad083fafbefdeae9a42ec19bdaaad8918dcf411/serverless/javascript/src/session.ts#L187-L223","documentation":"DatabaseError thrown when the pipeline response to a describe request has an unexpected shape: results is missing or empty, or the first result is neither an error nor a describe result carrying a payload. Unlike a describe error this signals a protocol or version mismatch — the server answered 200 but not with the structure the client expects.","triggerScenarios":"Pointing the client at a server that does not implement the v3 pipeline describe request; test mocks or proxies returning arbitrary 200 JSON; an intermediary rewriting the response body between server and client.","commonSituations":"Self-hosted sqld/hrana server versions older than the describe support; URL pointing at a different product's endpoint that still returns 200 JSON; shallow fetch stubs in unit tests that return generic fixtures for every request.","solutions":["Confirm the URL targets a current Turso SQL-over-HTTP v3 endpoint (curl the /v3/pipeline describe request and inspect the JSON shape)","Align versions: update the server or the client so both speak the same protocol","Fix test mocks to return a well-formed PipelineResponse whose first result is { type: 'ok', response: { type: 'describe', result: {...} } }"],"exampleFix":"// before — URL returns 200 but is not a v3 pipeline server\nconst db = connect({ url: \"https://api.example.com\" });\nawait db.prepare(\"SELECT 1\"); // Unexpected describe response\n\n// after\nconst db = connect({ url: \"https://my-db-my-org.turso.io\" });\nawait db.prepare(\"SELECT 1\");","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  await db.prepare(\"SELECT 1\"); // cheap protocol smoke test\n} catch (e) {\n  if (e instanceof Error && e.message === \"Unexpected describe response\") {\n    // endpoint is not speaking v3 pipeline: verify URL and server version,\n    // do not retry blindly — it will fail identically\n    throw new Error(\"database endpoint is not a Turso v3 pipeline server\");\n  }\n  throw e;\n}","preventionTips":["Pin client and server versions that are known compatible; upgrade them together","Verify new endpoints with a one-line prepare('SELECT 1') probe at boot","Make fetch test mocks return structurally correct PipelineResponse objects"],"tags":["protocol","compatibility","server-version","javascript"],"backgroundTag":"unexpected-api-response","analyzedSha":"bad083fafbefdeae9a42ec19bdaaad8918dcf411","analyzedAt":"2026-08-16T23:12:11.798Z","schemaVersion":2},"datasetVersion":"2026-08-17T04:17:16.089Z"}