{"record":{"id":"404d6a2c1f9fb836","repo":"Budibase/budibase","slug":"sqs-error","errorCode":"sqs_error","errorMessage":"error while running SQS query, please try again later","messagePattern":"error while running SQS query, please try again later","errorType":"exception","errorClass":"CouchDBError","httpStatus":null,"severity":"error","filePath":"packages/backend-core/src/db/couch/DatabaseImpl.ts","lineNumber":421,"sourceCode":"    const args: { url: string; method: string; cookie: string; body?: any } = {\n      url,\n      method,\n      cookie: this.couchInfo.cookie,\n    }\n    if (body) {\n      args.body = body\n    }\n    return this.performCall(() => {\n      return async () => {\n        const response = await directCouchUrlCall(args)\n        const text = await response.text()\n        if (response.status > 300) {\n          let json\n          try {\n            json = JSON.parse(text)\n          } catch (err) {\n            console.error(`SQS error: ${text}`)\n            throw new CouchDBError(\n              \"error while running SQS query, please try again later\",\n              { name: \"sqs_error\", status: response.status }\n            )\n          }\n          throw json\n        }\n        return JSON.parse(text) as T\n      }\n    })\n  }\n\n  async sql<T extends Document>(\n    sql: string,\n    parameters?: SqlQueryBinding\n  ): Promise<T[]> {\n    const dbName = this.name\n    const url = `/${dbName}/${SQLITE_DESIGN_DOC_ID}`\n    sqlLog(SqlClient.SQL_LITE, sql, parameters)","sourceCodeStart":403,"sourceCodeEnd":439,"githubUrl":"https://github.com/Budibase/budibase/blob/a81a902e9a8fe55b467d106765f6638f12e35c49/packages/backend-core/src/db/couch/DatabaseImpl.ts#L403-L439","documentation":"_sqlQuery wraps the SQS (SQL query service) endpoint of CouchDB; when the response status is >300 the body is parsed as JSON and rethrown, but if the body is not valid JSON, a generic CouchDBError with name 'sqs_error' and the upstream status is thrown instead. It indicates the SQL sidecar returned a non-JSON error (gateway error, crash, proxy HTML, timeout).","triggerScenarios":"Calling db.sql(query) / sqlPurgeDocument / sqlDiskCleanup when the SQS service is down, misconfigured (wrong COUCH_DB_SQL_URL / COUCH_DB_SQS_PORT), or returns an HTML/plain-text error page.","commonSituations":"Dev stack where the SQS container failed to start; reverse proxy returning 502/504 HTML; hitting a CouchDB without the SQL endpoint; transient overload on the query service.","solutions":["Check the SQS service is running and healthy (correct COUCH_DB_SQL_URL / COUCH_DB_SQS_PORT in env)","Retry the query with backoff if the status was 5xx (transient gateway error)","Log/inspect the console output 'SQS error: <text>' to see the raw upstream body","Simplify the SQL query and re-run to rule out a query crash in the service","Upgrade/repair the CouchDB SQL sidecar if it consistently returns non-JSON errors"],"exampleFix":"// before\nconst rows = await db.sql(`SELECT * FROM users`)\n// after\ntry {\n  const rows = await db.sql(`SELECT * FROM users`)\n} catch (e) {\n  if (e.name === \"sqs_error\") {\n    await sleep(1000)\n    return db.sql(`SELECT * FROM users`)\n  }\n  throw e\n}","handlingStrategy":"retry","validationCode":"if (!process.env.COUCH_DB_SQL_URL && !process.env.COUCH_DB_URL) {\n  throw new Error(\"SQS endpoint not configured\")\n}","typeGuard":"function isSqsError(e: unknown): e is { name: \"sqs_error\"; status: number } {\n  return typeof e === \"object\" && e !== null && (e as any).name === \"sqs_error\"\n}","tryCatchPattern":"try {\n  return await db.sql(query)\n} catch (e) {\n  if (isSqsError(e) && e.status >= 500) return withRetry(() => db.sql(query), 3)\n  throw e\n}","preventionTips":["Health-check the SQS endpoint before heavy query workloads","Keep queries simple and paginate large scans","Monitor COUCH_DB_SQS_PORT service uptime in dev/prod"],"tags":["couchdb","sql","service-unavailable","retry"],"backgroundTag":"upstream-service-error","analyzedSha":"a81a902e9a8fe55b467d106765f6638f12e35c49","analyzedAt":"2026-08-29T01:03:10.972Z","schemaVersion":2},"datasetVersion":"2026-08-29T02:17:18.158Z"}