Budibase/budibase · error

CouchDB username not set

Error message

CouchDB username not set

What it means

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.

Source

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

    password: env.COUCH_DB_PASSWORD || "",
  })
}

export const parseCouchConnection = (
  connection: string,
  credentials?: { user: string; password: string }
) => {
  // 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!,

View on GitHub (pinned to a81a902e9a)

Solutions

1. Set the COUCH_DB_USER environment variable (and password) before booting
2. Include credentials in the CouchDB URL: http://user:password@host:5984
3. Pass { user, password } explicitly to the connection helper
4. Verify the config-loading code actually populates the credentials object (no undefined key names)

Example fix

// before
const url = process.env.COUCH_DB_URL || "http://localhost:5984"
// after
const url = process.env.COUCH_DB_URL || `http://${env.COUCH_DB_USER}:${env.COUCH_DB_PASSWORD}@localhost:5984`

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

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

When it happens

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

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

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 password not set
• No Microsoft datasource configuration found
• Unable to connect without URL or database
• Workspace DB not found - self-host users using cloud don't h
• DB does not exist

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