Budibase/budibase · error

mountBudibaseApp requires a valid appUrl

Error message

mountBudibaseApp requires a valid appUrl

What it means

After validating the target element, mountBudibaseApp normalizes appUrl via normalizeAppPath; if the result is falsy the URL is not a usable app path and the function throws. The appUrl must resolve to a valid app path (e.g. /app-name) used for resolution and embed location.

Source

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

// Attach to window so the HTML template can call this when it loads
window.loadBudibase = loadBudibase

export const mountBudibaseApp = async ({
  target,
  appUrl,
  appId,
  initialPath,
  onNavigate,
}: MountBudibaseAppOptions) => {
  if (!target || !(target instanceof HTMLElement)) {
    throw new Error("mountBudibaseApp requires a target HTMLElement")
  }

  const appPath = normalizeAppPath(appUrl)
  const appHash = getHash(appUrl)
  if (!appPath) {
    throw new Error("mountBudibaseApp requires a valid appUrl")
  }

  const resolvedAppId = appId || (await resolveAppIdFromPath(appPath))

  window["##BUDIBASE_APP_ID##"] = resolvedAppId
  window["##BUDIBASE_EMBED_LOCATION##"] = appPath

  const resolvedInitialPath = initialPath
    ? normalizeRoutePath(initialPath)
    : appHash
      ? normalizeRoutePath(appHash.replace(/^#/, ""))
      : undefined

  if (resolvedInitialPath && getCurrentPath() !== resolvedInitialPath) {
    await navigateToPath(resolvedInitialPath)
  }

  if (app) {

View on GitHub (pinned to a81a902e9a)

Solutions

1. Pass appUrl as the published app path, e.g. "/my-app" (matching /app<url> of the published app)
2. Check what normalizeAppPath expects and confirm your string survives normalization (leading slash, path-only, no origin)
3. Copy the app path directly from the Budibase app's embed/publish settings

Example fix

// before
mountBudibaseApp({ target: el, appUrl: "https://example.com/apps/my-app" })
// after
mountBudibaseApp({ target: el, appUrl: "/my-app" })

const appPath = appUrl?.startsWith("/") ? appUrl : undefined
if (!appPath) throw new Error("appUrl must be a path like /my-app")
mountBudibaseApp({ target: el, appUrl: appPath })

const isValidAppUrl = (u: unknown): u is string =>
  typeof u === "string" && u.trim().length > 0 && u.startsWith("/")

try {
  await mountBudibaseApp({ target: el, appUrl })
} catch (err) {
  if ((err as Error).message.includes("requires a valid appUrl")) {
    // correct appUrl to the published app path and retry
  } else throw err
}

When it happens

Trigger: Calling mountBudibaseApp with appUrl undefined, empty string, a full external URL, or any value that normalizeAppPath cannot convert into a valid app path.

Common situations: Forgetting the appUrl option entirely; passing the absolute URL of the host page instead of the app path; trailing junk or malformed paths stripped away by normalization; copying the wrong link when configuring the embed.

Related errors

• mountBudibaseApp requires a target HTMLElement
• Could not resolve Budibase app for path: ${appPath}
• Invalid URL.
• Only HTTP(S) URLs are allowed.
• URL must not include credentials.

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