Budibase/budibase · error

Could not resolve Budibase app for path: ${appPath}

Error message

Could not resolve Budibase app for path: ${appPath}

What it means

In the client SDK, resolveAppIdFromPath matches a given appPath against the list of published apps fetched via API.getPublishedApps(), comparing `/app${app.url}` to the normalized path. If no published app matches, or the match has no prodId (production app ID), the embed cannot proceed and this error is thrown.

Source

Thrown at packages/client/src/index.ts:171

}

const normalizeAppPath = (pathOrUrl: string) => {
  const pathname = getPathname(pathOrUrl).replace(/\/$/, "")
  if (!pathname) {
    return ""
  }
  if (pathname.startsWith("/app/")) {
    return pathname
  }
  return pathname.startsWith("/") ? `/app${pathname}` : `/app/${pathname}`
}

const resolveAppIdFromPath = async (appPath: string) => {
  const publishedApps = await API.getPublishedApps()
  const pathToMatch = appPath.replace(/\/$/, "")
  const matched = publishedApps.find(app => `/app${app.url}` === pathToMatch)
  if (!matched?.prodId) {
    throw new Error(`Could not resolve Budibase app for path: ${appPath}`)
  }
  return matched.prodId
}

const normalizeRoutePath = (path: string) => {
  if (!path) {
    return "/"
  }
  const [pathname = "/", query = ""] = path.split("?")
  const normalizedPathname = pathname.startsWith("/")
    ? pathname
    : `/${pathname}`
  if (!query) {
    return normalizedPathname
  }
  return `${normalizedPathname}?${query}`
}

View on GitHub (pinned to a81a902e9a)

Solutions

1. Pass the appId option explicitly to mountBudibaseApp so path resolution is skipped
2. Verify the app is published (deployed to production) and its URL matches: path must be exactly `/app${app.url}` after stripping a trailing slash
3. Log/check API.getPublishedApps() output and correct the appUrl to one of the published app URLs

Example fix

// before
mountBudibaseApp({ target: el, appUrl: "/my-app" })
// Error: Could not resolve Budibase app for path: /my-app
// after: pass appId explicitly
mountBudibaseApp({ target: el, appId: "app_dev_123 prodId", appUrl: "/my-app" })

const apps = await API.getPublishedApps()
const normalized = appUrl.replace(/\/$/, "")
const match = apps.find(a => `/app${a.url}` === normalized && a.prodId)
if (!match) throw new Error(`No published app matches ${normalized}; pass appId explicitly`)

const isPublishedApp = (a: { url?: string; prodId?: string } | undefined): a is { url: string; prodId: string } =>
  Boolean(a && a.url && a.prodId)

try {
  await mountBudibaseApp({ target: el, appUrl })
} catch (err) {
  if ((err as Error).message.startsWith("Could not resolve Budibase app")) {
    // fall back: mount with an explicit appId or show a config error
  } else throw err
}

When it happens

Trigger: Calling mountBudibaseApp without an explicit appId where appPath (normalized from appUrl) does not equal `/app<url>` of any published app, or the matching app has no prodId — e.g. the app is unpublished, the URL is wrong, or the path has extra segments/trailing content.

Common situations: Embedding an app whose production deployment doesn't exist (app only in dev); appUrl typo or wrong domain path; published app list unavailable/empty due to API failure; app renamed so its URL changed; passing a full URL where only the app path is expected.

Related errors

• mountBudibaseApp requires a target HTMLElement
• mountBudibaseApp requires a valid appUrl
• Workspace DB not found - self-host users using cloud don't h
• CouchDB username not set
• CouchDB password not set

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