nexu-io/open-design · error · Error

The registered Open Design runtime is unavailable and cannot

Error message

The registered Open Design runtime is unavailable and cannot be launched (${plan.reason}).

What it means

Thrown by ensureMcpDaemonUrl() when the daemon is unreachable and the bootstrap planner returns action 'none' (cannot auto-launch). planMcpDaemonBootstrap returns 'none' with a reason in three cases: `bootstrap-unavailable` (env OD_MCP_BOOTSTRAP_COMMAND missing/empty), `invalid-bootstrap-command` (command is not an absolute path), or `invalid-bootstrap-args` (OD_MCP_BOOTSTRAP_ARGS absent/not-a-string-array/missing `--headless`). The reason is interpolated into the message so the caller knows which precondition failed.

Source

Thrown at apps/daemon/src/mcp-bootstrap.ts:129

    && env.OD_MCP_BOOTSTRAP_ARGS.length > 0;

  let daemonUrl: string | null = registeredBootstrapTarget
    ? await discoverTargetDaemonUrl(env, 800)
    : await resolveDaemonUrl({
        env,
        flagUrl,
        timeoutMs: 800,
      });
  const daemonReachable =
    daemonUrl != null && await probeDaemon(daemonUrl);
  const plan = planMcpDaemonBootstrap({
    daemonReachable,
    env,
    explicitDaemonUrl,
  });
  if (plan.action === "none") {
    if (daemonUrl != null) return daemonUrl;
    throw new Error(
      `The registered Open Design runtime is unavailable and cannot be launched (${plan.reason}).`,
    );
  }

  await spawnBootstrap(plan);
  const deadline = Date.now() + timeoutMs;
  while (Date.now() < deadline) {
    await sleep(DEFAULT_BOOTSTRAP_POLL_MS);
    daemonUrl = registeredBootstrapTarget
      ? await discoverTargetDaemonUrl(env, 300)
      : await resolveDaemonUrl({
          env,
          flagUrl: null,
          timeoutMs: 300,
        });
    if (daemonUrl != null && await probeDaemon(daemonUrl)) return daemonUrl;
  }
  throw new Error(

View on GitHub (pinned to 5be4028344)

Solutions

1. Start the daemon first (`pnpm tools-dev` in dev, or launch the packaged app) so the MCP server can reach it without bootstrapping.
2. Set OD_DAEMON_URL to a running daemon's base URL to bypass discovery and bootstrap entirely.
3. If you intend to use auto-launch: set OD_MCP_BOOTSTRAP_COMMAND to an absolute path, OD_MCP_BOOTSTRAP_ARGS to a JSON string array that includes `--headless`.
4. Inspect the reason in the error message — it names exactly which precondition is missing.

Example fix

# before — MCP server started with no daemon and no bootstrap env
export OD_DAEMON_URL=http://127.0.0.1:17456/api
od mcp

# or set up bootstrap explicitly
export OD_MCP_BOOTSTRAP_COMMAND=/usr/local/bin/od-daemon
export OD_MCP_BOOTSTRAP_ARGS='["daemon","--headless"]'

import { isAbsolute } from 'node:path';

function canBootstrap(env: NodeJS.ProcessEnv): boolean {
  const cmd = env.OD_MCP_BOOTSTRAP_COMMAND;
  if (!cmd) return false;
  if (!isAbsolute(cmd)) return false;
  let args: unknown = null;
  try { args = JSON.parse(env.OD_MCP_BOOTSTRAP_ARGS ?? ''); } catch { return false; }
  return Array.isArray(args) && args.every((a) => typeof a === 'string') && args.includes('--headless');
}

if (!canBootstrap(process.env) && !process.env.OD_DAEMON_URL) {
  throw new Error('Set OD_DAEMON_URL to a running daemon, or set OD_MCP_BOOTSTRAP_COMMAND (absolute) + OD_MCP_BOOTSTRAP_ARGS (JSON array with --headless).');
}

try {
  await ensureMcpDaemonUrl();
} catch (error) {
  if (error instanceof Error && error.message.includes('registered Open Design runtime is unavailable')) {
    // Fall back to an explicit URL or instruct the user to start the daemon.
    throw new Error('Could not reach or launch the Open Design daemon. Start it with `pnpm tools-dev` or set OD_DAEMON_URL.');
  }
  throw error;
}

When it happens

Trigger: Running `od mcp` (or embedding the MCP server) outside a packaged runtime that pre-sets OD_MCP_BOOTSTRAP_COMMAND/ARGS, with no daemon already running and no OD_DAEMON_URL set. Each reason maps to a specific misconfiguration: missing env var, relative command path, or malformed/missing --headless arg.

Common situations: Developer runs the MCP server standalone without first starting the daemon; packaged bootstrap env vars were not propagated (e.g. stripped by a wrapper shell); OD_DAEMON_URL points at a dead daemon and bootstrap env is absent; the bootstrap command path is relative because the packaged installer layout changed.

Related errors

• Open Design was launched headlessly but its daemon did not b
• project arg omitted and active context lookup failed: ${erro
• daemon ${resp.status} on ${url}: ${body || resp.statusText}
• ARTIFACT_MANIFEST_INVALID
• ARTIFACT_MANIFEST_REQUIRED

AI-assisted analysis of nexu-io/open-design@5be4028344 (2026-08-12). Data as JSON: /api/errors/a1a8b4642bf2a04a. Report an issue: GitHub.