{"record":{"id":"a1a8b4642bf2a04a","repo":"nexu-io/open-design","slug":"the-registered-open-design-runtime-is-unavailable","errorCode":null,"errorMessage":"The registered Open Design runtime is unavailable and cannot be launched (${plan.reason}).","messagePattern":"The registered Open Design runtime is unavailable and cannot be launched \\((.+?)\\)\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"apps/daemon/src/mcp-bootstrap.ts","lineNumber":129,"sourceCode":"    && env.OD_MCP_BOOTSTRAP_ARGS.length > 0;\n\n  let daemonUrl: string | null = registeredBootstrapTarget\n    ? await discoverTargetDaemonUrl(env, 800)\n    : await resolveDaemonUrl({\n        env,\n        flagUrl,\n        timeoutMs: 800,\n      });\n  const daemonReachable =\n    daemonUrl != null && await probeDaemon(daemonUrl);\n  const plan = planMcpDaemonBootstrap({\n    daemonReachable,\n    env,\n    explicitDaemonUrl,\n  });\n  if (plan.action === \"none\") {\n    if (daemonUrl != null) return daemonUrl;\n    throw new Error(\n      `The registered Open Design runtime is unavailable and cannot be launched (${plan.reason}).`,\n    );\n  }\n\n  await spawnBootstrap(plan);\n  const deadline = Date.now() + timeoutMs;\n  while (Date.now() < deadline) {\n    await sleep(DEFAULT_BOOTSTRAP_POLL_MS);\n    daemonUrl = registeredBootstrapTarget\n      ? await discoverTargetDaemonUrl(env, 300)\n      : await resolveDaemonUrl({\n          env,\n          flagUrl: null,\n          timeoutMs: 300,\n        });\n    if (daemonUrl != null && await probeDaemon(daemonUrl)) return daemonUrl;\n  }\n  throw new Error(","sourceCodeStart":111,"sourceCodeEnd":147,"githubUrl":"https://github.com/nexu-io/open-design/blob/5be4028344c2eb4c667c5a97bda8f750c5597ef7/apps/daemon/src/mcp-bootstrap.ts#L111-L147","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Start the daemon first (`pnpm tools-dev` in dev, or launch the packaged app) so the MCP server can reach it without bootstrapping.","Set OD_DAEMON_URL to a running daemon's base URL to bypass discovery and bootstrap entirely.","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`.","Inspect the reason in the error message — it names exactly which precondition is missing."],"exampleFix":"# before — MCP server started with no daemon and no bootstrap env\nexport OD_DAEMON_URL=http://127.0.0.1:17456/api\nod mcp\n\n# or set up bootstrap explicitly\nexport OD_MCP_BOOTSTRAP_COMMAND=/usr/local/bin/od-daemon\nexport OD_MCP_BOOTSTRAP_ARGS='[\"daemon\",\"--headless\"]'","handlingStrategy":"validation","validationCode":"import { isAbsolute } from 'node:path';\n\nfunction canBootstrap(env: NodeJS.ProcessEnv): boolean {\n  const cmd = env.OD_MCP_BOOTSTRAP_COMMAND;\n  if (!cmd) return false;\n  if (!isAbsolute(cmd)) return false;\n  let args: unknown = null;\n  try { args = JSON.parse(env.OD_MCP_BOOTSTRAP_ARGS ?? ''); } catch { return false; }\n  return Array.isArray(args) && args.every((a) => typeof a === 'string') && args.includes('--headless');\n}\n\nif (!canBootstrap(process.env) && !process.env.OD_DAEMON_URL) {\n  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).');\n}","typeGuard":null,"tryCatchPattern":"try {\n  await ensureMcpDaemonUrl();\n} catch (error) {\n  if (error instanceof Error && error.message.includes('registered Open Design runtime is unavailable')) {\n    // Fall back to an explicit URL or instruct the user to start the daemon.\n    throw new Error('Could not reach or launch the Open Design daemon. Start it with `pnpm tools-dev` or set OD_DAEMON_URL.');\n  }\n  throw error;\n}","preventionTips":["Start the daemon before launching the MCP server when possible.","In packaged runtimes, ensure OD_MCP_BOOTSTRAP_COMMAND (absolute path) and OD_MCP_BOOTSTRAP_ARGS (JSON array containing --headless) are set.","Prefer OD_DAEMON_URL for explicit daemon targeting."],"tags":["mcp","bootstrap","daemon","environment","launch"],"backgroundTag":null,"analyzedSha":"5be4028344c2eb4c667c5a97bda8f750c5597ef7","analyzedAt":"2026-08-12T12:03:58.812Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}