{"record":{"id":"ed804a40b1c6e6b5","repo":"Budibase/budibase","slug":"unable-to-retrieve-user-list","errorCode":null,"errorMessage":"Unable to retrieve user list","messagePattern":"Unable to retrieve user list","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/worker/src/utilities/users.ts","lineNumber":14,"sourceCode":"import { tenancy, db as dbCore } from \"@budibase/backend-core\"\n\nexport async function checkAnyUserExists() {\n  try {\n    const db = tenancy.getGlobalDB()\n    const users = await db.allDocs(\n      dbCore.getGlobalUserParams(null, {\n        include_docs: true,\n        limit: 1,\n      })\n    )\n    return users && users.rows.length >= 1\n  } catch (err) {\n    throw new Error(\"Unable to retrieve user list\")\n  }\n}\n","sourceCodeStart":1,"sourceCodeEnd":17,"githubUrl":"https://github.com/Budibase/budibase/blob/a81a902e9a8fe55b467d106765f6638f12e35c49/packages/worker/src/utilities/users.ts#L1-L17","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check CouchDB health and connectivity (curl the CouchDB endpoint) — the generic message hides the real cause, so inspect server logs for the original error","Verify COUCH_DB URL and credentials environment variables are correct","Ensure the databases have been initialized (run init/bootstrap) before querying users","Improve the catch to rethrow or wrap the original error (err) so diagnostics aren't lost"],"exampleFix":"// before\n} catch (err) {\n  throw new Error(\"Unable to retrieve user list\")\n}\n// after\n} catch (err: any) {\n  throw new Error(`Unable to retrieve user list: ${err.message}`)","handlingStrategy":"try-catch","validationCode":"// verify DB reachability first\nconst health = await fetch(`${COUCH_DB_URL}/_up`)\nif (!health.ok) throw new Error(\"CouchDB is not reachable\")","typeGuard":"null","tryCatchPattern":"try {\n  await checkAnyUserExists()\n} catch (e) {\n  if (e.message === \"Unable to retrieve user list\") {\n    // inspect server logs for the swallowed original DB error\n  }\n}","preventionTips":["Ensure CouchDB is running and reachable before dependent calls","Verify COUCH_DB URL/credentials in the environment","Run DB initialization/bootstrap on fresh installs","Wrap with the original error to preserve root cause in logs"],"tags":["database","couchdb","network","users"],"backgroundTag":"database-unavailable","analyzedSha":"a81a902e9a8fe55b467d106765f6638f12e35c49","analyzedAt":"2026-08-29T01:03:10.972Z","schemaVersion":2},"datasetVersion":"2026-08-29T02:17:18.158Z"}