[aionui-web] could not open the browser automatically

Error message

[aionui-web] could not open the browser automatically: ${openResult.reason}

What it means

Warning printed when the CLI's static-server (frontend-only path) mode tried to auto-open the user's browser via openBrowserUrl and it failed. The server is still running fine; only the convenience of opening the URL automatically was lost. The reason string from openBrowserUrl explains the underlying cause (e.g. no BROWSER, headless environment, unsupported platform opener).

Solutions

Ignore the warning and open handle.localUrl manually in a browser.
Pass the no-auto-open flag (or disable autoOpenBrowser in options) in headless/CI environments.
Install xdg-open (xdg-utils package) or set $BROWSER to a valid browser command on Linux.
Use port forwarding (ssh -L) when running remotely and open the local URL.

Example fix

# before
aionui-web start  # warns: could not open the browser automatically

# after
aionui-web start --no-open  # (or equivalent flag) then open http://localhost:<port> manually

Defensive patterns

Strategy: fallback

Validate before calling

const isHeadless = !process.env.DISPLAY && !process.env.WAYLAND_DISPLAY && process.platform === 'linux';
const autoOpenBrowser = !isHeadless && !process.env.CI;

Try / catch

const openResult = openBrowserUrl(handle.localUrl);
if (!openResult.ok) {
  // non-fatal: server is running; just surface URL for manual open
  console.warn(`Open manually: ${handle.localUrl} (${openResult.reason})`);
}

Prevention

Disable auto-open in Docker/CI/SSH environments.
Print the local URL unconditionally so manual open is always possible.
On Linux, ensure xdg-utils is installed or set $BROWSER.

When it happens

Trigger: Starting with auto-open enabled on a headless/SSH session, a container/CI environment, a server without xdg-open/open/start, or with an invalid $BROWSER env var.

Common situations: Running the web CLI inside Docker or over SSH without X forwarding; minimal Linux images lacking xdg-open; CI pipelines that start the server; $BROWSER set to a broken command.

Related errors

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

Appendix: source

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

    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.`);
      } else {
        console.warn(`[aionui-web] could not open the browser automatically: ${openResult.reason}`);
      }
    }
    console.log('');
    console.log('Press Ctrl+C to stop.');
  } else {
    const handle = await startWebHost({
      app: {
        version,
        isPackaged: true,
        resourcesPath: cliRoot,
        userDataPath: dataDir,
      },
      staticDir,
      port,
      allowRemote,
      dataDir,
      logDir,
      dirs: {

View on GitHub (pinned to 711aa0550e)