Budibase/budibase · error · CouchDBError

sqs_error

sqs_error

Error message

error while running SQS query, please try again later

What it means

_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).

Source

Thrown at packages/backend-core/src/db/couch/DatabaseImpl.ts:421

    const args: { url: string; method: string; cookie: string; body?: any } = {
      url,
      method,
      cookie: this.couchInfo.cookie,
    }
    if (body) {
      args.body = body
    }
    return this.performCall(() => {
      return async () => {
        const response = await directCouchUrlCall(args)
        const text = await response.text()
        if (response.status > 300) {
          let json
          try {
            json = JSON.parse(text)
          } catch (err) {
            console.error(`SQS error: ${text}`)
            throw new CouchDBError(
              "error while running SQS query, please try again later",
              { name: "sqs_error", status: response.status }
            )
          }
          throw json
        }
        return JSON.parse(text) as T
      }
    })
  }

  async sql<T extends Document>(
    sql: string,
    parameters?: SqlQueryBinding
  ): Promise<T[]> {
    const dbName = this.name
    const url = `/${dbName}/${SQLITE_DESIGN_DOC_ID}`
    sqlLog(SqlClient.SQL_LITE, sql, parameters)

View on GitHub (pinned to a81a902e9a)

Solutions

1. Check the SQS service is running and healthy (correct COUCH_DB_SQL_URL / COUCH_DB_SQS_PORT in env)
2. Retry the query with backoff if the status was 5xx (transient gateway error)
3. Log/inspect the console output 'SQS error: <text>' to see the raw upstream body
4. Simplify the SQL query and re-run to rule out a query crash in the service
5. Upgrade/repair the CouchDB SQL sidecar if it consistently returns non-JSON errors

Example fix

// before
const rows = await db.sql(`SELECT * FROM users`)
// after
try {
  const rows = await db.sql(`SELECT * FROM users`)
} catch (e) {
  if (e.name === "sqs_error") {
    await sleep(1000)
    return db.sql(`SELECT * FROM users`)
  }
  throw e
}

if (!process.env.COUCH_DB_SQL_URL && !process.env.COUCH_DB_URL) {
  throw new Error("SQS endpoint not configured")
}

function isSqsError(e: unknown): e is { name: "sqs_error"; status: number } {
  return typeof e === "object" && e !== null && (e as any).name === "sqs_error"
}

try {
  return await db.sql(query)
} catch (e) {
  if (isSqsError(e) && e.status >= 500) return withRetry(() => db.sql(query), 3)
  throw e
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• DB does not exist
• ${err.message}
• CouchDB error: ${err.message}
• Unable to get bulk documents: ${missingIds}
• Unable to remove doc without a valid _id and _rev.

AI-assisted analysis of Budibase/budibase@a81a902e9a (2026-08-29). Data as JSON: /api/errors/404d6a2c1f9fb836. Report an issue: GitHub.