{"record":{"id":"03e13c7b4dfb2793","repo":"Budibase/budibase","slug":"mountbudibaseapp-requires-a-valid-appurl","errorCode":null,"errorMessage":"mountBudibaseApp requires a valid appUrl","messagePattern":"mountBudibaseApp requires a valid appUrl","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/client/src/index.ts","lineNumber":327,"sourceCode":"\n// Attach to window so the HTML template can call this when it loads\nwindow.loadBudibase = loadBudibase\n\nexport const mountBudibaseApp = async ({\n  target,\n  appUrl,\n  appId,\n  initialPath,\n  onNavigate,\n}: MountBudibaseAppOptions) => {\n  if (!target || !(target instanceof HTMLElement)) {\n    throw new Error(\"mountBudibaseApp requires a target HTMLElement\")\n  }\n\n  const appPath = normalizeAppPath(appUrl)\n  const appHash = getHash(appUrl)\n  if (!appPath) {\n    throw new Error(\"mountBudibaseApp requires a valid appUrl\")\n  }\n\n  const resolvedAppId = appId || (await resolveAppIdFromPath(appPath))\n\n  window[\"##BUDIBASE_APP_ID##\"] = resolvedAppId\n  window[\"##BUDIBASE_EMBED_LOCATION##\"] = appPath\n\n  const resolvedInitialPath = initialPath\n    ? normalizeRoutePath(initialPath)\n    : appHash\n      ? normalizeRoutePath(appHash.replace(/^#/, \"\"))\n      : undefined\n\n  if (resolvedInitialPath && getCurrentPath() !== resolvedInitialPath) {\n    await navigateToPath(resolvedInitialPath)\n  }\n\n  if (app) {","sourceCodeStart":309,"sourceCodeEnd":345,"githubUrl":"https://github.com/Budibase/budibase/blob/a81a902e9a8fe55b467d106765f6638f12e35c49/packages/client/src/index.ts#L309-L345","documentation":"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.","triggerScenarios":"Calling mountBudibaseApp with appUrl undefined, empty string, a full external URL, or any value that normalizeAppPath cannot convert into a valid app path.","commonSituations":"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.","solutions":["Pass appUrl as the published app path, e.g. \"/my-app\" (matching /app<url> of the published app)","Check what normalizeAppPath expects and confirm your string survives normalization (leading slash, path-only, no origin)","Copy the app path directly from the Budibase app's embed/publish settings"],"exampleFix":"// before\nmountBudibaseApp({ target: el, appUrl: \"https://example.com/apps/my-app\" })\n// after\nmountBudibaseApp({ target: el, appUrl: \"/my-app\" })","handlingStrategy":"validation","validationCode":"const appPath = appUrl?.startsWith(\"/\") ? appUrl : undefined\nif (!appPath) throw new Error(\"appUrl must be a path like /my-app\")\nmountBudibaseApp({ target: el, appUrl: appPath })","typeGuard":"const isValidAppUrl = (u: unknown): u is string =>\n  typeof u === \"string\" && u.trim().length > 0 && u.startsWith(\"/\")","tryCatchPattern":"try {\n  await mountBudibaseApp({ target: el, appUrl })\n} catch (err) {\n  if ((err as Error).message.includes(\"requires a valid appUrl\")) {\n    // correct appUrl to the published app path and retry\n  } else throw err\n}","preventionTips":["Copy appUrl straight from the app's publish/embed settings","Pass a path-only value (leading slash, no protocol or host)","Validate appUrl against the published apps list before mounting"],"tags":["client-sdk","embedding","argument-validation","url"],"backgroundTag":"invalid-argument","analyzedSha":"a81a902e9a8fe55b467d106765f6638f12e35c49","analyzedAt":"2026-08-29T01:03:10.972Z","schemaVersion":2},"datasetVersion":"2026-08-29T02:17:18.158Z"}