Budibase/budibase · error · HTTPError

Workspace app should be defined

Error message

Workspace app should be defined

What it means

addLink fetches the target workspace app and throws HTTP 500 'Workspace app should be defined' when sdk.workspaceApps.get returns nothing. This is an internal invariant failure: the caller supplied a workspaceAppId that does not resolve to an existing workspace app, so a navigation link cannot be appended.

Source

Thrown at packages/server/src/sdk/workspace/navigation/index.ts:18

import { HTTPError } from "@budibase/backend-core"
import sdk from "../.."
import { AppNavigation } from "@budibase/types"

export async function addLink({
  label,
  url,
  roleId,
  workspaceAppId,
}: {
  label: string
  url: string
  roleId: string
  workspaceAppId: string
}) {
  const workspaceApp = await sdk.workspaceApps.get(workspaceAppId)
  if (!workspaceApp) {
    throw new HTTPError("Workspace app should be defined", 500)
  }
  workspaceApp.navigation.links ??= []
  workspaceApp.navigation.links.push({
    text: label,
    url,
    roleId,
    type: "link",
  })

  await sdk.workspaceApps.update(workspaceApp)
}

export async function deleteLink(route: string, workspaceAppId: string) {
  const workspaceApp = (await sdk.workspaceApps.get(workspaceAppId!))!
  workspaceApp.navigation.links ??= []

  // Filter out top level links pointing to these URLs
  const updatedLinks = workspaceApp.navigation.links.filter(

View on GitHub (pinned to a81a902e9a)

Solutions

1. Verify the workspaceAppId exists via sdk.workspaceApps.get or the apps API before calling addLink
2. Re-fetch the current workspace app list and use a fresh ID if the app was recreated
3. Ensure the call runs in the workspace context that owns the app

Example fix

// before
await addLink({ workspaceAppId: staleId, ... }) // app deleted -> 500
// after
const app = await sdk.workspaceApps.get(workspaceAppId)
if (app) await addLink({ workspaceAppId: app._id!, ... })

const app = await sdk.workspaceApps.get(workspaceAppId)
if (!app) throw new Error(`Workspace app ${workspaceAppId} not found; cannot add link`)

try {
  await navigation.addLink({ workspaceAppId, label, url, roleId })
} catch (err) {
  if (err instanceof HTTPError && err.status === 500 && /should be defined/.test(err.message)) {
    // stale workspaceAppId — refresh app list and retry once with a valid ID
    return
  }
  throw err
}

When it happens

Trigger: Calling addLink with a workspaceAppId that is undefined, deleted, or belongs to a different workspace — e.g. a stale ID cached in automation/script code, or a route param that never matched a real app document.

Common situations: Apps deleted while a client still holds their ID; cross-workspace ID reuse; copy-pasted IDs between dev/prod environments.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• Workspace app not found
• Workspace app not found ${workspaceAppId}
• Agent not found
• Operation not found
• gotoFunc must be a function, found a "${typeof gotoFunc}" in

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