{"record":{"id":"4fd9e653e30268e5","repo":"vercel/ai","slug":"acp-executable-must-be-a-bare-command-name-without","errorCode":null,"errorMessage":"ACP executable must be a bare command name without a path; received ${JSON.stringify(implementation.executable)}.","messagePattern":"ACP executable must be a bare command name without a path; received (.+?)\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/harness-acp/src/v1/implementation.ts","lineNumber":74,"sourceCode":"): void {\n  const { source } = implementation;\n  if (source.type === 'npm-locked') {\n    if (source.packageJson.length === 0) {\n      throw new Error('ACP source.packageJson must not be empty.');\n    }\n    if (source.pnpmLockYaml.length === 0) {\n      throw new Error('ACP source.pnpmLockYaml must not be empty.');\n    }\n    if (source.pnpmWorkspaceYaml?.length === 0) {\n      throw new Error('ACP source.pnpmWorkspaceYaml must not be empty.');\n    }\n  } else if (source.type === 'npm-simple') {\n    validateNpmSimpleSource({ source });\n  } else if (source.command.trim().length === 0) {\n    throw new Error('ACP source.command must not be empty.');\n  }\n  if (!EXECUTABLE_NAME_REGEXP.test(implementation.executable)) {\n    throw new Error(\n      `ACP executable must be a bare command name without a path; received ${JSON.stringify(implementation.executable)}.`,\n    );\n  }\n\n  validateForwardEnvironment({ forwardEnv: implementation.forwardEnv });\n  validateForwardEnvironment({ forwardEnv: implementation.credentialEnv });\n  validateEnvironment({ env: implementation.env });\n  const forwardedKeys = new Set(implementation.forwardEnv ?? []);\n  const credentialKeys = new Set(implementation.credentialEnv ?? []);\n  for (const key of credentialKeys) {\n    if (forwardedKeys.has(key)) {\n      throw new Error(\n        `ACP runtime environment key ${JSON.stringify(key)} cannot be configured in both forwardEnv and credentialEnv.`,\n      );\n    }\n  }\n  for (const key of Object.keys(implementation.env ?? {})) {\n    if (forwardedKeys.has(key)) {","sourceCodeStart":56,"sourceCodeEnd":92,"githubUrl":"https://github.com/vercel/ai/blob/69428b1f8b037e4d118fb4853428d5c4e620493c/packages/harness-acp/src/v1/implementation.ts#L56-L92","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\ncreateACPV1({ executable: '/usr/local/bin/claude-code-acp --stdio' });\n// after\ncreateACPV1({ executable: 'claude-code-acp', args: ['--stdio'] });","handlingStrategy":"validation","validationCode":"const EXECUTABLE_NAME_REGEXP = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;\nif (!EXECUTABLE_NAME_REGEXP.test(implementation.executable)) {\n  throw new Error(`executable must be a bare name, got: ${implementation.executable}`);\n}","typeGuard":"function isBareExecutableName(name) {\n  return typeof name === 'string' && /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(name);\n}","tryCatchPattern":"try {\n  const impl = createACPV1(settings);\n} catch (err) {\n  if (err instanceof Error && err.message.startsWith('ACP executable must be a bare command name')) {\n    console.error('Strip paths/flags from executable; move flags into args and rely on PATH');\n  }\n  throw err;\n}","preventionTips":["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"],"tags":["configuration","validation","process-launch"],"backgroundTag":"invalid-config-value","analyzedSha":"69428b1f8b037e4d118fb4853428d5c4e620493c","analyzedAt":"2026-08-30T12:32:21.016Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}