iOfficeAI/AionUi · warning

To enable backend: download aioncore and set AIONUI_BACKE

Error message

   To enable backend: download aioncore and set AIONUI_BACKEND_BIN.

What it means

Instructional line in the FRONTEND-ONLY warning block naming the remediation: download aioncore and set AIONUI_BACKEND_BIN. It's the actionable footer of the graceful-degradation warning emitted when backend binary resolution fails.

Source

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

  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) {
        console.log(`[aionui-web] opened ${handle.localUrl} in your browser.`);

View on GitHub (pinned to 711aa0550e)

Solutions

1. Download the aioncore release matching your platform.
2. export AIONUI_BACKEND_BIN=/path/to/aioncore (persist in shell profile or service Environment config).
3. Verify with a preflight existence check before starting the CLI.

Example fix

# before
aionui-web start

# after
curl -L -o /usr/local/bin/aioncore <aioncore-release-url>
chmod +x /usr/local/bin/aioncore
AIONUI_BACKEND_BIN=/usr/local/bin/aioncore aionui-web start

if (!fs.existsSync(process.env.AIONUI_BACKEND_BIN ?? '')) {
  console.error('Download aioncore and set AIONUI_BACKEND_BIN before starting.');
  process.exit(1);
}

When it happens

Trigger: Printed whenever the backend binary is missing; the fix it names (env var + download) is the resolution path.

Common situations: First-time setup; onboarding docs skipped; deployment scripts missing the env var; version upgrades that changed the download location.

Related errors

• ⚠️ Backend binary not found — starting in FRONTEND-ONLY mod
• Missing: ${backendBin}

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