Budibase/budibase · error

CouchDB password not set

Error message

CouchDB password not set

What it means

parseCouchConnection resolves the CouchDB password from URL auth or credentials and throws when neither provides one. A username may exist, but the library will not connect without a password to build the basic-auth cookie.

Source

Thrown at packages/backend-core/src/db/couch/connections.ts:32

  // clean out any auth credentials
  const urlInfo = getUrlInfo(connection)
  let username
  let password
  if (urlInfo.auth?.username) {
    // set from url
    username = urlInfo.auth.username
  } else if (credentials?.user) {
    username = credentials?.user
  } else {
    throw new Error("CouchDB username not set")
  }
  if (urlInfo.auth?.password) {
    // set from url
    password = urlInfo.auth.password
  } else if (credentials?.password) {
    password = credentials?.password
  } else {
    throw new Error("CouchDB password not set")
  }
  const authCookie = Buffer.from(`${username}:${password}`).toString("base64")
  let sqlUrl = env.COUCH_DB_SQL_URL
  if (!sqlUrl && urlInfo.url) {
    const parsed = new URL(urlInfo.url)
    parsed.port = env.COUCH_DB_SQS_PORT
    sqlUrl = parsed.toString().replace(/\/$/, "")
  }
  return {
    url: urlInfo.url!,
    // clean out any auth credentials
    sqlUrl: getUrlInfo(sqlUrl).url,
    auth: {
      username: username,
      password: password,
    },
    cookie: `Basic ${authCookie}`,
  }

View on GitHub (pinned to a81a902e9a)

Solutions

1. Set the COUCH_DB_PASSWORD environment variable
2. Embed the password in the CouchDB URL (URL-encode special characters)
3. Pass an explicit { user, password } credentials object
4. Check secret injection (k8s secret / .env file) actually mounts the value

Example fix

// before
const password = config.dbPassword // undefined
// after
const password = config.dbPassword ?? process.env.COUCH_DB_PASSWORD
if (!password) throw new Error("Set COUCH_DB_PASSWORD")

if (!process.env.COUCH_DB_PASSWORD && !/\/[^/@]+:[^@]+@/.test(process.env.COUCH_DB_URL ?? "")) {
  throw new Error("CouchDB password missing: set COUCH_DB_PASSWORD or embed in URL")
}

try {
  return getCouchInfo()
} catch (e) {
  if (e.message === "CouchDB password not set") {
    console.error("Set COUCH_DB_PASSWORD or credentials before initializing db")
  }
  throw e
}

When it happens

Trigger: getCouchInfo() invoked when COUCH_DB_URL lacks a password in the auth segment and the credentials object/env has no password (COUCH_DB_PASSWORD unset or empty).

Common situations: Deployed with COUCH_DB_USER but forgotten COUCH_DB_PASSWORD; password containing special chars dropped by URL parsing; secrets manager returning undefined for the key; CouchDB started in admin-party mode with no password configured.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• CouchDB username not set
• No Microsoft datasource configuration found
• Unable to connect without URL or database
• Cannot enforce SSO without an activated configuration
• Workspace DB not found - self-host users using cloud don't h

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