The web UI will load but API calls will fail until a back

Error message

   The web UI will load but API calls will fail until a backend is available.

What it means

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.

Source

Thrown at packages/web-cli/src/index.ts:172

  }

  console.log(`[aionui-web] version    : ${version}`);
  console.log(`[aionui-web] data dir   : ${dataDir}`);
  console.log(`[aionui-web] log dir    : ${logDir}`);
  console.log(`[aionui-web] static dir : ${staticDir}`);
  console.log(`[aionui-web] backend bin: ${backendBin}`);
  console.log(`[aionui-web] launching  : port=${port} allowRemote=${allowRemote}`);

  const backendAvailable = fs.existsSync(backendBin);

  if (!backendAvailable) {
    // Graceful degradation: serve the SPA shell without spawning backend.
    // API calls from the browser will 502/ECONNREFUSED — frontend is expected
    // to surface this to the user (e.g. "backend missing" banner).
    console.warn('');
    console.warn('⚠️  Backend binary not found — starting in FRONTEND-ONLY mode.');
    console.warn(`   Missing: ${backendBin}`);
    console.warn('   The web UI will load but API calls will fail until a backend is available.');
    console.warn('   To enable backend: download aioncore and set AIONUI_BACKEND_BIN.');
    console.warn('');

    const handle = await startStaticServer({
      staticDir,
      backendPort: 0, // invalid port → API proxy will fail cleanly
      port,
      allowRemote,
    });
    currentHandle = handle;

    console.log('');
    console.log('AionUi WebUI (frontend only) is ready');
    console.log(`  Local  : ${handle.localUrl}`);
    if (handle.networkUrl) console.log(`  Network: ${handle.networkUrl}`);
    if (autoOpenBrowser) {
      const openResult = openBrowserUrl(handle.localUrl);
      if (openResult.ok) {

View on GitHub (pinned to 711aa0550e)

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.

Defensive patterns

Strategy: fallback

Validate before calling

if (!backendAvailable && !process.env.AIONUI_ALLOW_FRONTEND_ONLY) {
  throw new Error('Backend required but not available; refusing frontend-only start.');
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of iOfficeAI/AionUi@711aa0550e (2026-08-28). Data as JSON: /api/errors/0b9f618837955409. Report an issue: GitHub.