vercel/ai · error · Error

Unsupported ACP protocol version ${JSON.stringify(version)}.

Error message

Unsupported ACP protocol version ${JSON.stringify(version)}. Supported versions: "v1".

What it means

createACP dispatches on the settings.version field and only supports 'v1' (the default when version is omitted). Any other string reaches the switch's default branch and throws, telling you the unsupported value and the supported list. This guards against typos or targeting a protocol version this package build does not implement.

Source

Thrown at packages/harness-acp/src/acp-harness.ts:156

    );
  }
  const version = (settings as { readonly version?: string }).version ?? 'v1';
  switch (version) {
    case 'v1': {
      const clientApp = settings.clientApp ?? ACP_CLIENT_APP;
      return createACPV1({
        settings,
        builtinTools:
          settings.builtinTools ?? (ACP_BUILTIN_TOOLS as TBuiltinTools),
        port: settings.port,
        portEndpoint: settings.portEndpoint,
        startupTimeoutMs: settings.startupTimeoutMs,
        clientApp,
        lifecycleStateSchema: acpResumeStateSchema,
      });
    }
    default:
      throw new Error(
        `Unsupported ACP protocol version ${JSON.stringify(version)}. Supported versions: "v1".`,
      );
  }
}

View on GitHub (pinned to 69428b1f8b)

Solutions

1. Set version to 'v1' or simply omit the version field (it defaults to 'v1').
2. Fix casing/typos in the version string ('V1' is not accepted).
3. Upgrade @ai-sdk/harness-acp if you need a newer protocol version.

Example fix

// before
createACP({ version: 'v2' }); // throws
// after
createACP({}); // version defaults to 'v1'

const SUPPORTED_ACP_VERSIONS = ['v1'] as const;
function validateAcpVersion(version?: string): void {
  if (version != null && !SUPPORTED_ACP_VERSIONS.includes(version as 'v1')) {
    throw new Error(`Unsupported ACP version ${version}; use 'v1' or omit.`);
  }
}

function isSupportedAcpVersion(v: unknown): v is 'v1' {
  return v === 'v1' || v === undefined;
}

When it happens

Trigger: Passing settings.version as any string other than 'v1' (or undefined) to createACP or a wrapper factory that forwards settings, e.g. { version: 'v2' } or a typo like { version: 'V1' }.

Common situations: Upgrading the SDK and copying a newer config that references a protocol version not present in the installed package version; case-sensitivity typos; probing for future versions.

Related errors

• Invalid argument for parameter output: Invalid output type.
• Continuation maxAgeMs must be a positive integer.
• ACP credentialEnv and credentialBrokering must be configured
• ACP credentialEnv and credentialBrokering must be configured
• ACP harnessId must be a stable kebab-case identifier; receiv

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