{"record":{"id":"a7487e1c57576de8","repo":"iOfficeAI/AionUi","slug":"backend-binary-not-found-starting-in-fronten","errorCode":null,"errorMessage":"⚠️  Backend binary not found — starting in FRONTEND-ONLY mode.","messagePattern":"⚠️  Backend binary not found — starting in FRONTEND-ONLY mode\\.","errorType":"console","errorClass":null,"httpStatus":null,"severity":"warning","filePath":"packages/web-cli/src/index.ts","lineNumber":170,"sourceCode":"    console.error(`  hint: pass --static-dir <path> pointing to the SPA build output`);\n    process.exit(1);\n  }\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) {","sourceCodeStart":152,"sourceCodeEnd":188,"githubUrl":"https://github.com/iOfficeAI/AionUi/blob/711aa0550ee183ea495dc33e2c05c7943b70a60a/packages/web-cli/src/index.ts#L152-L188","documentation":"This is a console warning (not a thrown error) emitted by the web CLI's start command when the configured aioncore backend binary cannot be found. The CLI deliberately degrades to FRONTEND-ONLY mode: it serves the SPA shell but API proxy calls will fail because no backend was spawned. It exists so the operator understands why the UI loads but every API request 502s/ECONNREFUSEDs.","triggerScenarios":"Running the web CLI start with AIONUI_BACKEND_BIN unset, pointing at a nonexistent path, or when the aioncore binary is not on PATH / not installed at the expected location.","commonSituations":"Fresh clone without downloading aioncore; AIONUI_BACKEND_BIN typo or relative path resolved from the wrong cwd; CI environment where the binary artifact wasn't fetched; after a rename/move of the backend binary.","solutions":["Set AIONUI_BACKEND_BIN to the absolute path of the aioncore binary and re-run start.","Download/install the aioncore backend release for your platform and verify the path exists.","If frontend-only mode is intentional (static preview), ignore the warning but expect API calls to fail.","Add a preflight check (fs.existsSync on the resolved backend path) to fail fast with a clearer message."],"exampleFix":"# before\naionui-web start  # backend missing, silent 502s later\n\n# after\nexport AIONUI_BACKEND_BIN=/opt/aioncore/bin/aioncore\naionui-web start","handlingStrategy":"validation","validationCode":"import fs from 'node:fs';\nconst bin = process.env.AIONUI_BACKEND_BIN ?? 'aioncore';\nconst backendAvailable = fs.existsSync(bin);\nif (!backendAvailable && !process.env.AIONUI_ALLOW_FRONTEND_ONLY) {\n  throw new Error(`Backend binary not found at '${bin}'. Set AIONUI_BACKEND_BIN.`);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always set AIONUI_BACKEND_BIN to an absolute path in deploy scripts.","Add a startup preflight that fails fast when the backend is required.","Log the resolved backend path at startup for easier diagnosis."],"tags":["backend-missing","cli","startup","frontend-only-mode"],"backgroundTag":"missing-backend-binary","analyzedSha":"711aa0550ee183ea495dc33e2c05c7943b70a60a","analyzedAt":"2026-08-28T07:56:06.558Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}