ACP executable must be a bare command name without a path; r

Error message

ACP executable must be a bare command name without a path; received ${JSON.stringify(implementation.executable)}.

What it means

implementation.executable must be a bare command name (letters/digits, optionally . _ -) with no path separators or arguments. The library spawns the executable via PATH resolution and refuses absolute/relative paths and anything with shell metacharacters. The message includes the received value for diagnosis.

Source

Thrown at packages/harness-acp/src/v1/implementation.ts:74

): void {
  const { source } = implementation;
  if (source.type === 'npm-locked') {
    if (source.packageJson.length === 0) {
      throw new Error('ACP source.packageJson must not be empty.');
    }
    if (source.pnpmLockYaml.length === 0) {
      throw new Error('ACP source.pnpmLockYaml must not be empty.');
    }
    if (source.pnpmWorkspaceYaml?.length === 0) {
      throw new Error('ACP source.pnpmWorkspaceYaml must not be empty.');
    }
  } else if (source.type === 'npm-simple') {
    validateNpmSimpleSource({ source });
  } else if (source.command.trim().length === 0) {
    throw new Error('ACP source.command must not be empty.');
  }
  if (!EXECUTABLE_NAME_REGEXP.test(implementation.executable)) {
    throw new Error(
      `ACP executable must be a bare command name without a path; received ${JSON.stringify(implementation.executable)}.`,
    );
  }

  validateForwardEnvironment({ forwardEnv: implementation.forwardEnv });
  validateForwardEnvironment({ forwardEnv: implementation.credentialEnv });
  validateEnvironment({ env: implementation.env });
  const forwardedKeys = new Set(implementation.forwardEnv ?? []);
  const credentialKeys = new Set(implementation.credentialEnv ?? []);
  for (const key of credentialKeys) {
    if (forwardedKeys.has(key)) {
      throw new Error(
        `ACP runtime environment key ${JSON.stringify(key)} cannot be configured in both forwardEnv and credentialEnv.`,
      );
    }
  }
  for (const key of Object.keys(implementation.env ?? {})) {
    if (forwardedKeys.has(key)) {

View on GitHub (pinned to 69428b1f8b)

Solutions

Pass only the bare binary name (e.g. 'claude-code-acp') and rely on PATH; move any path/args into source or the args array.
Install the executable somewhere on PATH (e.g. npm i -g) if it is not globally available.
If you need an absolute binary, resolve it so the basename goes into executable and its directory into PATH via env.

Example fix

// before
createACPV1({ executable: '/usr/local/bin/claude-code-acp --stdio' });
// after
createACPV1({ executable: 'claude-code-acp', args: ['--stdio'] });

Defensive patterns

Strategy: validation

Validate before calling

const EXECUTABLE_NAME_REGEXP = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
if (!EXECUTABLE_NAME_REGEXP.test(implementation.executable)) {
  throw new Error(`executable must be a bare name, got: ${implementation.executable}`);
}

Type guard

function isBareExecutableName(name) {
  return typeof name === 'string' && /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name);
}

Try / catch

try {
  const impl = createACPV1(settings);
} catch (err) {
  if (err instanceof Error && err.message.startsWith('ACP executable must be a bare command name')) {
    console.error('Strip paths/flags from executable; move flags into args and rely on PATH');
  }
  throw err;
}

Prevention

Install the ACP binary somewhere on PATH and reference it by bare name
Never concatenate command-line flags into executable; use args
Use path.basename() if deriving the name from a resolved path

When it happens

Trigger: createACPV1 called with executable values like '/usr/local/bin/claude-code-acp', './bin/acp', 'node index.js', or names containing spaces or '/', all of which fail EXECUTABLE_NAME_REGEXP.

Common situations: Copying a full binary path from `which` output, embedding CLI flags into executable instead of args, Windows path (C:\...) configs, or concatenating command+args into one string.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

AI-assisted analysis of vercel/ai@69428b1f8b (2026-08-30). Data as JSON: /api/errors/4fd9e653e30268e5. Report an issue: GitHub.