⚠️ Backend binary not found — starting in FRONTEND-ONLY mod

Error message

⚠️  Backend binary not found — starting in FRONTEND-ONLY mode.

What it means

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.

Source

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

    console.error(`  hint: pass --static-dir <path> pointing to the SPA build output`);
    process.exit(1);
  }

  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) {

View on GitHub (pinned to 711aa0550e)

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.

Example fix

# before
aionui-web start  # backend missing, silent 502s later

# after
export AIONUI_BACKEND_BIN=/opt/aioncore/bin/aioncore
aionui-web start

Defensive patterns

Strategy: validation

Validate before calling

import fs from 'node:fs';
const bin = process.env.AIONUI_BACKEND_BIN ?? 'aioncore';
const backendAvailable = fs.existsSync(bin);
if (!backendAvailable && !process.env.AIONUI_ALLOW_FRONTEND_ONLY) {
  throw new Error(`Backend binary not found at '${bin}'. Set AIONUI_BACKEND_BIN.`);
}

Prevention

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.

When it happens

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

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

Related errors

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