vercel/ai · error

ACP npm package version must be an exact semantic version; r

Error message

ACP npm package version must be an exact semantic version; received ${JSON.stringify(source.packageVersion)}.

What it means

When provided, source.packageVersion for 'npm-simple' sources must be an exact semver (MAJOR.MINOR.PATCH, optional -prerelease/+build). Ranges like ^1.0.0, >=2, latest, or dist-tags are rejected so installs are reproducible. Omitting packageVersion entirely is allowed (meaning latest).

Source

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

    ...implementation.env,
  };
}

function validateNpmSimpleSource({
  source,
}: {
  source: ACPNpmSimpleSource;
}): void {
  if (!PACKAGE_NAME_REGEXP.test(source.packageName)) {
    throw new Error(
      `ACP npm package name is invalid: ${JSON.stringify(source.packageName)}.`,
    );
  }
  if (
    source.packageVersion != null &&
    !EXACT_SEMVER_REGEXP.test(source.packageVersion)
  ) {
    throw new Error(
      `ACP npm package version must be an exact semantic version; received ${JSON.stringify(source.packageVersion)}.`,
    );
  }
}

function validateEnvironment({
  env,
}: {
  env: Readonly<Record<string, string>> | undefined;
}): void {
  for (const [key, value] of Object.entries(env ?? {})) {
    if (!ENVIRONMENT_VARIABLE_NAME_REGEXP.test(key)) {
      throw new Error(
        `ACP environment variable name is invalid: ${JSON.stringify(key)}.`,
      );
    }
    if (value.includes('\0')) {
      throw new Error(`ACP runtime environment value for ${key} contains NUL.`);

View on GitHub (pinned to 69428b1f8b)

Solutions

1. Pin the exact version, e.g. '1.2.3', stripped of any range operators or 'v' prefix.
2. If you want the latest, delete packageVersion instead of passing 'latest'.
3. Get the exact version via `npm view <pkg> version` and paste it.

Example fix

// before
createACPV1({ source: { type: 'npm-simple', packageName: 'claude-code-acp', packageVersion: '^1.0.0' } });
// after
createACPV1({ source: { type: 'npm-simple', packageName: 'claude-code-acp', packageVersion: '1.4.2' } });

const EXACT_SEMVER_REGEXP = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
if (source.packageVersion != null && !EXACT_SEMVER_REGEXP.test(source.packageVersion)) {
  throw new Error(`packageVersion must be exact semver, got: ${source.packageVersion}`);
}

function isExactSemver(v) {
  return v == null || /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.test(v);
}

try {
  const impl = createACPV1(settings);
} catch (err) {
  if (err instanceof Error && err.message.includes('exact semantic version')) {
    console.error('Pin an exact x.y.z version (no ^, ~, v prefix, or ranges)');
  }
  throw err;
}

When it happens

Trigger: createACPV1 with source.type 'npm-simple' and packageVersion values like '^1.2.3', '~2.0.0', '>=1', 'latest', '1.2', or 'v1.2.3' (leading v is not accepted by the regex).

Common situations: Copying a version range from package.json dependencies, using the string from `npm outdated`, or prefixing with 'v' as printed by some CLIs.

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

• ACP source.packageJson must not be empty.
• ACP source.pnpmWorkspaceYaml must not be empty.
• ACP npm package name is invalid: ${JSON.stringify(source.pac
• Invalid argument for parameter output: Invalid output type.
• Continuation maxAgeMs must be a positive integer.

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