Budibase/budibase · error

Unable to retrieve user list

Error message

Unable to retrieve user list

What it means

checkAnyUserExists queries the users database (a CouchDB all-docs view with limit 1) to determine whether any user exists. If that query throws for any reason, the catch block swallows the original error and rethrows a generic Error "Unable to retrieve user list", losing the root cause.

Source

Thrown at packages/worker/src/utilities/users.ts:14

import { tenancy, db as dbCore } from "@budibase/backend-core"

export async function checkAnyUserExists() {
  try {
    const db = tenancy.getGlobalDB()
    const users = await db.allDocs(
      dbCore.getGlobalUserParams(null, {
        include_docs: true,
        limit: 1,
      })
    )
    return users && users.rows.length >= 1
  } catch (err) {
    throw new Error("Unable to retrieve user list")
  }
}

View on GitHub (pinned to a81a902e9a)

Solutions

1. Check CouchDB health and connectivity (curl the CouchDB endpoint) — the generic message hides the real cause, so inspect server logs for the original error
2. Verify COUCH_DB URL and credentials environment variables are correct
3. Ensure the databases have been initialized (run init/bootstrap) before querying users
4. Improve the catch to rethrow or wrap the original error (err) so diagnostics aren't lost

Example fix

// before
} catch (err) {
  throw new Error("Unable to retrieve user list")
}
// after
} catch (err: any) {
  throw new Error(`Unable to retrieve user list: ${err.message}`)

// verify DB reachability first
const health = await fetch(`${COUCH_DB_URL}/_up`)
if (!health.ok) throw new Error("CouchDB is not reachable")

null

try {
  await checkAnyUserExists()
} catch (e) {
  if (e.message === "Unable to retrieve user list") {
    // inspect server logs for the swallowed original DB error
  }
}

When it happens

Trigger: Any failure of the underlying DB query inside checkAnyUserExists (called via userExists): CouchDB down/unreachable, connection timeout, database not initialized, permission/auth error, or malformed view request.

Common situations: CouchDB container not running during local development; network/DNS issues between worker and CouchDB; first-run bootstrap where the database doesn't exist yet; CouchDB credentials misconfigured in environment.

Related errors

• DB does not exist
• ${err.message}
• CouchDB error: ${err.message}
• Replication failed - ${JSON.stringify(err)}
• Escalation ${escalationId} not found

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