{"record":{"id":"85c6184d284a1969","repo":"Budibase/budibase","slug":"couchdb-username-not-set","errorCode":null,"errorMessage":"CouchDB username not set","messagePattern":"CouchDB username not set","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/backend-core/src/db/couch/connections.ts","lineNumber":24,"sourceCode":"    password: env.COUCH_DB_PASSWORD || \"\",\n  })\n}\n\nexport const parseCouchConnection = (\n  connection: string,\n  credentials?: { user: string; password: string }\n) => {\n  // clean out any auth credentials\n  const urlInfo = getUrlInfo(connection)\n  let username\n  let password\n  if (urlInfo.auth?.username) {\n    // set from url\n    username = urlInfo.auth.username\n  } else if (credentials?.user) {\n    username = credentials?.user\n  } else {\n    throw new Error(\"CouchDB username not set\")\n  }\n  if (urlInfo.auth?.password) {\n    // set from url\n    password = urlInfo.auth.password\n  } else if (credentials?.password) {\n    password = credentials?.password\n  } else {\n    throw new Error(\"CouchDB password not set\")\n  }\n  const authCookie = Buffer.from(`${username}:${password}`).toString(\"base64\")\n  let sqlUrl = env.COUCH_DB_SQL_URL\n  if (!sqlUrl && urlInfo.url) {\n    const parsed = new URL(urlInfo.url)\n    parsed.port = env.COUCH_DB_SQS_PORT\n    sqlUrl = parsed.toString().replace(/\\/$/, \"\")\n  }\n  return {\n    url: urlInfo.url!,","sourceCodeStart":6,"sourceCodeEnd":42,"githubUrl":"https://github.com/Budibase/budibase/blob/a81a902e9a8fe55b467d106765f6638f12e35c49/packages/backend-core/src/db/couch/connections.ts#L6-L42","documentation":"parseCouchConnection resolves CouchDB credentials from the URL auth section or explicit credentials, and throws when neither provides a username. The library refuses to build a connection without knowing which user to authenticate as.","triggerScenarios":"Calling getCouchInfo()/parseCouchConnection when COUCH_DB_URL has no user:pass@ part and the passed credentials object has no user field (or env vars are empty).","commonSituations":"Missing COUCH_DB_USER env var in deployment; URL stripped of basic-auth for security; credentials object built from optional config that is undefined in dev; renaming config keys.","solutions":["Set the COUCH_DB_USER environment variable (and password) before booting","Include credentials in the CouchDB URL: http://user:password@host:5984","Pass { user, password } explicitly to the connection helper","Verify the config-loading code actually populates the credentials object (no undefined key names)"],"exampleFix":"// before\nconst url = process.env.COUCH_DB_URL || \"http://localhost:5984\"\n// after\nconst url = process.env.COUCH_DB_URL || `http://${env.COUCH_DB_USER}:${env.COUCH_DB_PASSWORD}@localhost:5984`","handlingStrategy":"validation","validationCode":"if (!process.env.COUCH_DB_USER && !/\\/[^/@]+:.*@/.test(process.env.COUCH_DB_URL ?? \"\")) {\n  throw new Error(\"CouchDB username missing: set COUCH_DB_USER or embed in URL\")\n}","typeGuard":null,"tryCatchPattern":"try {\n  return getCouchInfo()\n} catch (e) {\n  if (e.message === \"CouchDB username not set\") {\n    console.error(\"Set COUCH_DB_USER / credentials before initializing db\")\n  }\n  throw e\n}","preventionTips":["Validate CouchDB env vars at process startup (fail fast)","Keep URL-embedded and env credentials in sync in docs/deploy scripts","Check secrets are injected in each environment (dev, CI, prod)"],"tags":["couchdb","configuration","env"],"backgroundTag":"missing-env-var","analyzedSha":"a81a902e9a8fe55b467d106765f6638f12e35c49","analyzedAt":"2026-08-29T01:03:10.972Z","schemaVersion":2},"datasetVersion":"2026-08-29T02:17:18.158Z"}