iOfficeAI/AionUi · error

[WebUI] /api/auth/status returned ${statusRes.status}

Error message

[WebUI] /api/auth/status returned ${statusRes.status}

What it means

Thrown when the aioncore backend's /api/auth/status endpoint responds with a non-2xx status during WebUI initial-password seeding. The HTTP status code is included in the message.

Source

Thrown at packages/desktop/src/process/bridge/webuiBridge.ts:59

  }
}

/**
 * On first Enable-WebUI click after a fresh install, the backend's users table
 * holds the seeded `system_default_user` row with an empty password_hash.
 * Probe /api/auth/status; if `needs_setup === true`, ask backend to generate
 * and persist a random password, then stash the plaintext for Settings to show
 * once. When the backend already has credentials (upgrade path handled by
 * ensureAdminUser, or a prior Enable-WebUI), this is a no-op.
 */
async function maybeSeedInitialPassword(): Promise<void> {
  const port = getBackendPort();
  if (!port) {
    throw new Error('[WebUI] Cannot start: aioncore is not running (globalThis.__backendPort unset)');
  }
  const statusRes = await fetch(`http://127.0.0.1:${port}/api/auth/status`);
  if (!statusRes.ok) {
    throw new Error(`[WebUI] /api/auth/status returned ${statusRes.status}`);
  }
  const statusJson = (await statusRes.json()) as { needs_setup?: boolean; data?: { needs_setup?: boolean } };
  const needsSetup = statusJson.needs_setup ?? statusJson.data?.needs_setup ?? false;
  if (!needsSetup) {
    setDesktopWebUIInitialPassword(undefined);
    return;
  }
  const resetRes = await fetch(`http://127.0.0.1:${port}/api/webui/reset-password`, { method: 'POST' });
  if (!resetRes.ok) {
    throw new Error(`[WebUI] /api/webui/reset-password returned ${resetRes.status}`);
  }
  const resetJson = (await resetRes.json()) as { data?: { new_password?: string }; new_password?: string };
  const newPassword = resetJson.data?.new_password ?? resetJson.new_password;
  if (!newPassword) {
    throw new Error('[WebUI] /api/webui/reset-password returned no new_password');
  }
  setDesktopWebUIInitialPassword(newPassword);
}

View on GitHub (pinned to 711aa0550e)

Solutions

  1. Retry once after a short delay — the backend may still be mounting routes when the port is already bound
  2. curl the endpoint directly to see the status and body: curl -i http://127.0.0.1:PORT/api/auth/status
  3. Check backend logs for errors around auth initialization
  4. Confirm the backend version exposes /api/auth/status (not renamed)
Defensive patterns

Strategy: retry

Validate before calling

const health = await fetch(`http://127.0.0.1:${port}/api/auth/status`).catch(() => null);
if (!health?.ok) { /* backend not ready; wait and retry */ }

Try / catch

catch (err) {
  if (/\/api\/auth\/status returned/.test(err.message)) {
    await delay(1000); return retry();
  }
  throw err;
}

Prevention

When it happens

Trigger: GET http://127.0.0.1:{port}/api/auth/status returns 4xx/5xx — backend auth routes not yet mounted, backend still initializing, or an internal backend error.

Common situations: Backend listening but still booting its HTTP routes, auth subsystem failure, or a backend version where the endpoint was renamed/removed.

Related errors

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