nexu-io/open-design · critical

vela binary not found; install vela or configure VELA_BIN

Error message

vela binary not found; install vela or configure VELA_BIN

What it means

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.

Source

Thrown at apps/daemon/src/integrations/vela.ts:1190

      'daemon',
    );
    throw new Error('AMR runtime def not registered');
  }
  const baseEnv = deps.baseEnv ?? process.env;
  const configuredEnv = withDefaultVelaApiUrl(
    deps.configuredEnv ?? {},
    baseEnv,
    deps.defaultApiUrl,
  );
  const launch = resolveAgentLaunch(def, configuredEnv);
  const bin = launch.selectedPath;
  if (!bin) {
    recordVelaAuthStage(
      deps.attempt,
      { stage: 'spawn_result', result: 'failed', errorKind: 'internal_error' },
      'daemon',
    );
    throw new Error('vela binary not found; install vela or configure VELA_BIN');
  }
  const env: NodeJS.ProcessEnv = {
    ...spawnEnvForAgent('amr', baseEnv, configuredEnv),
    ...velaLoginAttributionEnv(deps.attribution),
    ...(deps.correlationEnv ?? {}),
    // The UUID is daemon-owned and written after configured/base env so a
    // child cannot replace the correlation key selected for this attempt.
    OPEN_DESIGN_AMR_AUTH_ATTEMPT_ID: deps.attempt.authAttemptId,
  };
  // This fallback-only change does not opt the child into a structured stage
  // protocol that the packaged Vela CLI cannot emit.
  delete env.OPEN_DESIGN_AMR_AUTH_STAGE_FORMAT;
  // Route through createCommandInvocation so an npm/Node-style `vela.cmd` or
  // `vela.bat` shim on Windows gets wrapped under `cmd.exe /d /s /c …` with
  // verbatim args, matching what `execAgentFile` / chat-run spawning do. A
  // direct `spawn(bin, args)` on a `.cmd` shim quietly fails to find the
  // shim's actual entry point. POSIX is unchanged (no wrapping needed).
  const invocation = createCommandInvocation({ command: bin, args: ['login'], env });

View on GitHub (pinned to 5be4028344)

Solutions

  1. Install vela (and ensure it is on PATH) or set VELA_BIN to an absolute path to the binary.
  2. For packaged runs, verify the bundled vela binary is present and the resolver includes its directory.
  3. Confirm the 'amr' agent def is registered (getAgentDef('amr') is non-null) before invoking login.

Example fix

// before
const launch = resolveAgentLaunch(def, configuredEnv);
if (!launch.selectedPath) throw new Error('vela binary not found; install vela or configure VELA_BIN');

// after (user-facing guidance before throwing)
const launch = resolveAgentLaunch(def, configuredEnv);
if (!launch.selectedPath) {
  throw new Error('vela binary not found; install vela or configure VELA_BIN');
}
// operator sets: export VELA_BIN=/usr/local/bin/vela
Defensive patterns

Strategy: validation

Validate before calling

import { existsSync } from 'node:fs';

function resolveVelaBin(): string | null {
  const fromEnv = process.env.VELA_BIN;
  if (fromEnv && existsSync(fromEnv)) return fromEnv;
  // fall back to PATH discovery if your runtime exposes it
  return null;
}

if (!resolveVelaBin()) {
  return { ok: false, reason: 'vela_binary_missing' };
}

Type guard

function isVelaBinaryMissing(err: unknown): boolean {
  return err instanceof Error && err.message === 'vela binary not found; install vela or configure VELA_BIN';
}

Try / catch

try {
  return await spawnVelaLoginAttempt(deps);
} catch (err) {
  if (err instanceof Error && err.message.includes('install vela or configure VELA_BIN')) {
    return { ok: false, reason: 'vela_binary_missing' };
  }
  throw err;
}

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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