vercel/ai · error · HarnessCapabilityUnsupportedError

${harnessId} does not support structured output through ACP.

Error message

${harnessId} does not support structured output through ACP.

What it means

Thrown by createSession in the ACP v1 harness when a structured-output (responseFormat.type === 'json') turn is requested but no outputSchemaMapping was configured. The ACP protocol needs an explicit mapping from the JSON schema to the agent's output format; without it the harness cannot translate the request, so it refuses up front with an 'unsupported' error instead of failing mid-turn.

Source

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

  };

  return {
    sessionId,
    isResume,
    doPromptTurn: async options => {
      await synchronizeSkills({
        skills: options.skills,
        abortSignal: options.abortSignal,
      });
      if (options.responseFormat?.type === 'json') {
        if (options.responseFormat.schema == null) {
          throw unsupported({
            harnessId,
            message: `${harnessId} requires a JSON schema for structured output.`,
          });
        }
        if (outputSchemaMapping == null) {
          throw unsupported({
            harnessId,
            message: `${harnessId} does not support structured output through ACP.`,
          });
        }
      }
      if (replayOnly) {
        throw new Error(
          `${harnessId} recovered this turn through disk replay only and has no restored ACP process for a subsequent prompt.`,
        );
      }
      if (options.abortSignal?.aborted) {
        throw (
          options.abortSignal.reason ??
          new DOMException('Aborted', 'AbortError')
        );
      }
      const prompt = convertHarnessPromptToACPTextBlocks({
        prompt: options.prompt,

View on GitHub (pinned to 69428b1f8b)

Solutions

Provide a valid outputSchemaMapping alongside the JSON responseFormat when creating the ACP v1 session.
If the harness cannot provide a mapping, remove responseFormat and request plain text output, parsing it yourself.
Check the harness documentation for ACP structured-output support before using responseFormat.type === 'json'.

Example fix

// before
await createACPV1({ responseFormat: { type: 'json' } });
// after
await createACPV1({
  responseFormat: { type: 'json' },
  outputSchemaMapping: mySchemaMapping,
});

Defensive patterns

Strategy: validation

Validate before calling

if (options.responseFormat?.type === 'json' && outputSchemaMapping == null) {
  throw new Error('Provide outputSchemaMapping for JSON structured output on ACP v1 harnesses');
}

Try / catch

try {
  await createACPV1(options);
} catch (e) {
  if (isUnsupportedError(e)) {
    // fall back to text output
    await createACPV1({ ...options, responseFormat: undefined });
  } else throw e;
}

Prevention

Only enable responseFormat.type === 'json' when an outputSchemaMapping is available for the harness
Centralize harness capability checks in one helper before session creation
Feature-flag structured output per harness type

When it happens

Trigger: Calling a turn/session API with options.responseFormat set to { type: 'json' } on an ACP v1 harness while outputSchemaMapping is null or undefined at the point createSession runs.

Common situations: Enabling structured output generically across harnesses without checking ACP support; forgetting to supply the ACP output-schema mapping option; using a harness/adapter version where the mapping is not wired through.

Related errors

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