{"record":{"id":"a6e0bc33b76109ea","repo":"nexu-io/open-design","slug":"vela-binary-not-found-install-vela-or-configure-v","errorCode":null,"errorMessage":"vela binary not found; install vela or configure VELA_BIN","messagePattern":"vela binary not found; install vela or configure VELA_BIN","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"apps/daemon/src/integrations/vela.ts","lineNumber":1190,"sourceCode":"      'daemon',\n    );\n    throw new Error('AMR runtime def not registered');\n  }\n  const baseEnv = deps.baseEnv ?? process.env;\n  const configuredEnv = withDefaultVelaApiUrl(\n    deps.configuredEnv ?? {},\n    baseEnv,\n    deps.defaultApiUrl,\n  );\n  const launch = resolveAgentLaunch(def, configuredEnv);\n  const bin = launch.selectedPath;\n  if (!bin) {\n    recordVelaAuthStage(\n      deps.attempt,\n      { stage: 'spawn_result', result: 'failed', errorKind: 'internal_error' },\n      'daemon',\n    );\n    throw new Error('vela binary not found; install vela or configure VELA_BIN');\n  }\n  const env: NodeJS.ProcessEnv = {\n    ...spawnEnvForAgent('amr', baseEnv, configuredEnv),\n    ...velaLoginAttributionEnv(deps.attribution),\n    ...(deps.correlationEnv ?? {}),\n    // The UUID is daemon-owned and written after configured/base env so a\n    // child cannot replace the correlation key selected for this attempt.\n    OPEN_DESIGN_AMR_AUTH_ATTEMPT_ID: deps.attempt.authAttemptId,\n  };\n  // This fallback-only change does not opt the child into a structured stage\n  // protocol that the packaged Vela CLI cannot emit.\n  delete env.OPEN_DESIGN_AMR_AUTH_STAGE_FORMAT;\n  // Route through createCommandInvocation so an npm/Node-style `vela.cmd` or\n  // `vela.bat` shim on Windows gets wrapped under `cmd.exe /d /s /c …` with\n  // verbatim args, matching what `execAgentFile` / chat-run spawning do. A\n  // direct `spawn(bin, args)` on a `.cmd` shim quietly fails to find the\n  // shim's actual entry point. POSIX is unchanged (no wrapping needed).\n  const invocation = createCommandInvocation({ command: bin, args: ['login'], env });","sourceCodeStart":1172,"sourceCodeEnd":1208,"githubUrl":"https://github.com/nexu-io/open-design/blob/5be4028344c2eb4c667c5a97bda8f750c5597ef7/apps/daemon/src/integrations/vela.ts#L1172-L1208","documentation":"Raised in spawnVelaLoginAttempt() after resolveAgentLaunch(def, configuredEnv) returns no selectedPath for the 'amr' agent def. The vela CLI binary could not be discovered on PATH and VELA_BIN was not set to a valid path. Recorded as auth stage spawn_result failed/internal_error before throwing.","triggerScenarios":"PATH does not contain vela and VELA_BIN is unset/empty, or the amr agent runtime def's resolver could not find a packaged/bundled binary. Happens on first run, in fresh containers, or after uninstalling vela.","commonSituations":"New machine without vela installed; packaged daemon whose bundled vela was deleted; VELA_BIN points at a path that does not exist; PATH was sanitized for the agent subprocess and dropped the vela directory.","solutions":["Install vela (and ensure it is on PATH) or set VELA_BIN to an absolute path to the binary.","For packaged runs, verify the bundled vela binary is present and the resolver includes its directory.","Confirm the 'amr' agent def is registered (getAgentDef('amr') is non-null) before invoking login."],"exampleFix":"// before\nconst launch = resolveAgentLaunch(def, configuredEnv);\nif (!launch.selectedPath) throw new Error('vela binary not found; install vela or configure VELA_BIN');\n\n// after (user-facing guidance before throwing)\nconst launch = resolveAgentLaunch(def, configuredEnv);\nif (!launch.selectedPath) {\n  throw new Error('vela binary not found; install vela or configure VELA_BIN');\n}\n// operator sets: export VELA_BIN=/usr/local/bin/vela","handlingStrategy":"validation","validationCode":"import { existsSync } from 'node:fs';\n\nfunction resolveVelaBin(): string | null {\n  const fromEnv = process.env.VELA_BIN;\n  if (fromEnv && existsSync(fromEnv)) return fromEnv;\n  // fall back to PATH discovery if your runtime exposes it\n  return null;\n}\n\nif (!resolveVelaBin()) {\n  return { ok: false, reason: 'vela_binary_missing' };\n}","typeGuard":"function isVelaBinaryMissing(err: unknown): boolean {\n  return err instanceof Error && err.message === 'vela binary not found; install vela or configure VELA_BIN';\n}","tryCatchPattern":"try {\n  return await spawnVelaLoginAttempt(deps);\n} catch (err) {\n  if (err instanceof Error && err.message.includes('install vela or configure VELA_BIN')) {\n    return { ok: false, reason: 'vela_binary_missing' };\n  }\n  throw err;\n}","preventionTips":["Set VELA_BIN to an absolute path in packaged/dev environments.","Confirm getAgentDef('amr') is registered before invoking login.","Validate the resolver's PATH includes the directory containing vela."],"tags":["config","integration","binary","vela"],"backgroundTag":null,"analyzedSha":"5be4028344c2eb4c667c5a97bda8f750c5597ef7","analyzedAt":"2026-08-12T12:03:58.812Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}