Workspace DB not found - self-host users using cloud don't h

Error message

Workspace DB not found - self-host users using cloud don't have workspace DBs

What it means

getWorkspaceDB resolves the current request's workspace (app) database from request context. If the deployment is self-hosted in 'using cloud' mode, workspace DBs are not provisioned locally, so the function refuses to return one. It signals that the caller is asking for a resource that does not exist in this deployment mode.

Source

Thrown at packages/backend-core/src/context/mainContext.ts:419

export function getAuditLogsDB(): Database {
  if (!getTenantId()) {
    throw new Error("No tenant ID found - cannot open audit log DB")
  }
  return getDB(getAuditLogDBName())
}

/**
 * Gets the workspace database based on whatever the request
 * contained, dev or prod.
 */
export function getWorkspaceDB(opts?: any): Database {
  const workspaceId = getWorkspaceId()
  if (!workspaceId) {
    throw new Error("Unable to retrieve workspace DB - no workspace ID.")
  }
  if (isSelfHostUsingCloud()) {
    throw new Error(
      "Workspace DB not found - self-host users using cloud don't have workspace DBs"
    )
  }
  return getDB(workspaceId, opts)
}

/**
 * This specifically gets the prod workspace ID, if the request
 * contained a development workspace ID, this will get the prod one.
 */
export function getProdWorkspaceDB(opts?: any): Database {
  const workspaceId = getWorkspaceId()
  if (!workspaceId) {
    throw new Error("Unable to retrieve prod DB - no workspace ID.")
  }
  return getDB(conversions.getProdWorkspaceID(workspaceId), opts)
}

View on GitHub (pinned to a81a902e9a)

Solutions

Verify the deployment mode: a self-host install should not run with cloud mode flags; correct SELF_HOSTED / cloud-related env vars and restart
If this is genuinely a cloud-only resource, route the request to the cloud service instead of opening a local workspace DB
Guard calls with isSelfHostUsingCloud() before requesting a workspace DB and use the appropriate API in that mode

Example fix

// before
const db = getWorkspaceDB()
// after
if (isSelfHostUsingCloud()) {
  throw new Error("Workspace DBs unavailable in self-host cloud mode")
}
const db = getWorkspaceDB()

Defensive patterns

Strategy: validation

Validate before calling

import { isSelfHostUsingCloud } from "@budibase/backend-core/context"
if (isSelfHostUsingCloud()) {
  // use cloud API instead of local workspace DB
}
const db = getWorkspaceDB()

Try / catch

try {
  const db = getWorkspaceDB()
  // ...
} catch (err) {
  if (err.message.includes("self-host users using cloud")) {
    // fall back to cloud path
  } else throw err
}

Prevention

Check deployment mode early at startup and branch data-access strategy accordingly
Centralize DB access behind a helper that handles self-host-cloud mode
Document that workspace DB helpers are unavailable in self-host-cloud mode

When it happens

Trigger: Calling getWorkspaceDB (or the db alias) inside a request context whose workspace ID resolves while isSelfHostUsingCloud() is true — i.e. a self-hosted install configured to use Budibase cloud services tries to open any workspace DB.

Common situations: Self-hosted environments misconfigured with cloud licensing/account settings; code paths (automations, API handlers) that assume a local app DB exists but run against a self-host-cloud hybrid install.

Related errors

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