{"record":{"id":"0b9f618837955409","repo":"iOfficeAI/AionUi","slug":"the-web-ui-will-load-but-api-calls-will-fail-un","errorCode":null,"errorMessage":"   The web UI will load but API calls will fail until a backend is available.","messagePattern":"   The web UI will load but API calls will fail until a backend is available\\.","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"packages/web-cli/src/index.ts","lineNumber":172,"sourceCode":"  }\n\n  console.log(`[aionui-web] version    : ${version}`);\n  console.log(`[aionui-web] data dir   : ${dataDir}`);\n  console.log(`[aionui-web] log dir    : ${logDir}`);\n  console.log(`[aionui-web] static dir : ${staticDir}`);\n  console.log(`[aionui-web] backend bin: ${backendBin}`);\n  console.log(`[aionui-web] launching  : port=${port} allowRemote=${allowRemote}`);\n\n  const backendAvailable = fs.existsSync(backendBin);\n\n  if (!backendAvailable) {\n    // Graceful degradation: serve the SPA shell without spawning backend.\n    // API calls from the browser will 502/ECONNREFUSED — frontend is expected\n    // to surface this to the user (e.g. \"backend missing\" banner).\n    console.warn('');\n    console.warn('⚠️  Backend binary not found — starting in FRONTEND-ONLY mode.');\n    console.warn(`   Missing: ${backendBin}`);\n    console.warn('   The web UI will load but API calls will fail until a backend is available.');\n    console.warn('   To enable backend: download aioncore and set AIONUI_BACKEND_BIN.');\n    console.warn('');\n\n    const handle = await startStaticServer({\n      staticDir,\n      backendPort: 0, // invalid port → API proxy will fail cleanly\n      port,\n      allowRemote,\n    });\n    currentHandle = handle;\n\n    console.log('');\n    console.log('AionUi WebUI (frontend only) is ready');\n    console.log(`  Local  : ${handle.localUrl}`);\n    if (handle.networkUrl) console.log(`  Network: ${handle.networkUrl}`);\n    if (autoOpenBrowser) {\n      const openResult = openBrowserUrl(handle.localUrl);\n      if (openResult.ok) {","sourceCodeStart":154,"sourceCodeEnd":190,"githubUrl":"https://github.com/iOfficeAI/AionUi/blob/711aa0550ee183ea495dc33e2c05c7943b70a60a/packages/web-cli/src/index.ts#L154-L190","documentation":"Informational line in the FRONTEND-ONLY warning block telling the operator that the static server will start and the UI will render, but every proxied API request will fail (502/ECONNREFUSED) because the server was started with backendPort 0. It sets expectations so the 502s later aren't mistaken for a server bug.","triggerScenarios":"Always printed as part of the backend-missing warning block; the actual API failures occur when the browser calls any /api route through the proxy pointed at invalid port 0.","commonSituations":"Operators opening the UI in frontend-only mode and then wondering why login/session/chat endpoints fail; using the web UI for pure static preview; demos without a backend.","solutions":["Treat this as expected in frontend-only mode: only static assets work.","Provide a backend (set AIONUI_BACKEND_BIN) and restart to get working API calls.","Surface a 'backend missing' banner in the frontend as the comment suggests, so end users see the cause in-UI."],"exampleFix":null,"handlingStrategy":"fallback","validationCode":"if (!backendAvailable && !process.env.AIONUI_ALLOW_FRONTEND_ONLY) {\n  throw new Error('Backend required but not available; refusing frontend-only start.');\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["In frontend-only mode, show a 'backend missing' banner in the UI so users aren't confused by failing API calls.","Health-check the API proxy endpoint after startup to detect frontend-only mode programmatically."],"tags":["frontend-only-mode","api-unavailable","cli"],"backgroundTag":"missing-backend-binary","analyzedSha":"711aa0550ee183ea495dc33e2c05c7943b70a60a","analyzedAt":"2026-08-28T07:56:06.558Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}