{"record":{"id":"86ed60d22388747a","repo":"vercel/ai","slug":"unsupported-acp-protocol-version-json-stringify","errorCode":null,"errorMessage":"Unsupported ACP protocol version ${JSON.stringify(version)}. Supported versions: \"v1\".","messagePattern":"Unsupported ACP protocol version (.+?)\\. Supported versions: \"v1\"\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"packages/harness-acp/src/acp-harness.ts","lineNumber":156,"sourceCode":"    );\n  }\n  const version = (settings as { readonly version?: string }).version ?? 'v1';\n  switch (version) {\n    case 'v1': {\n      const clientApp = settings.clientApp ?? ACP_CLIENT_APP;\n      return createACPV1({\n        settings,\n        builtinTools:\n          settings.builtinTools ?? (ACP_BUILTIN_TOOLS as TBuiltinTools),\n        port: settings.port,\n        portEndpoint: settings.portEndpoint,\n        startupTimeoutMs: settings.startupTimeoutMs,\n        clientApp,\n        lifecycleStateSchema: acpResumeStateSchema,\n      });\n    }\n    default:\n      throw new Error(\n        `Unsupported ACP protocol version ${JSON.stringify(version)}. Supported versions: \"v1\".`,\n      );\n  }\n}\n","sourceCodeStart":138,"sourceCodeEnd":161,"githubUrl":"https://github.com/vercel/ai/blob/69428b1f8b037e4d118fb4853428d5c4e620493c/packages/harness-acp/src/acp-harness.ts#L138-L161","documentation":"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.","triggerScenarios":"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' }.","commonSituations":"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.","solutions":["Set version to 'v1' or simply omit the version field (it defaults to 'v1').","Fix casing/typos in the version string ('V1' is not accepted).","Upgrade @ai-sdk/harness-acp if you need a newer protocol version."],"exampleFix":"// before\ncreateACP({ version: 'v2' }); // throws\n// after\ncreateACP({}); // version defaults to 'v1'","handlingStrategy":"validation","validationCode":"const SUPPORTED_ACP_VERSIONS = ['v1'] as const;\nfunction validateAcpVersion(version?: string): void {\n  if (version != null && !SUPPORTED_ACP_VERSIONS.includes(version as 'v1')) {\n    throw new Error(`Unsupported ACP version ${version}; use 'v1' or omit.`);\n  }\n}","typeGuard":"function isSupportedAcpVersion(v: unknown): v is 'v1' {\n  return v === 'v1' || v === undefined;\n}","tryCatchPattern":null,"preventionTips":["Omit the version field unless you specifically need a non-default protocol.","Use the literal type 'v1' (const-asserted) in config builders so typos fail at compile time.","Check installed package docs before referencing newer protocol versions."],"tags":["configuration","versioning","validation"],"backgroundTag":"unsupported-version","analyzedSha":"69428b1f8b037e4d118fb4853428d5c4e620493c","analyzedAt":"2026-08-30T12:32:21.016Z","schemaVersion":2},"datasetVersion":"2026-08-30T13:17:10.514Z"}