vercel/ai · error · HarnessCapabilityUnsupportedError

Harness 'pi' does not support structured output.

Error message

Harness 'pi' does not support structured output.

What it means

The Pi harness is a coding-agent harness that produces free-form streamed output and cannot honor `responseFormat` of type 'json'. When a prompt turn requests structured output, the adapter throws HarnessCapabilityUnsupportedError, a typed capability error carrying the harness id.

Source

Thrown at packages/harness-pi/src/pi-session.ts:1344

      type: 'resume-session',
      harnessId: HARNESS_ID,
      specificationVersion: 'harness-v1',
      data: sessionFileName ? { sessionFileName } : {},
    };
  };

  const sessionImpl: HarnessV1Session = {
    sessionId: input.sessionId,
    isResume: input.isResume,
    // Pi has no bridge to attach to and no on-disk event log to replay; its
    // only resume path is restoring the session file on a fresh/snapshotted
    // sandbox, i.e. `rerun`.

    doPromptTurn: async (
      promptOpts: HarnessV1PromptTurnOptions,
    ): Promise<HarnessV1PromptControl> => {
      if (promptOpts.responseFormat?.type === 'json') {
        throw new HarnessCapabilityUnsupportedError({
          message: "Harness 'pi' does not support structured output.",
          harnessId: HARNESS_ID,
        });
      }
      return runTurn({
        text: extractUserText(promptOpts.prompt),
        ...(promptOpts.model ? { model: promptOpts.model } : {}),
        skills: promptOpts.skills,
        tools: promptOpts.tools ?? [],
        instructions: promptOpts.instructions,
        emit: promptOpts.emit,
        abortSignal: promptOpts.abortSignal,
      });
    },

    doContinueTurn: async (
      continueOpts: HarnessV1ContinueTurnOptions,
    ): Promise<HarnessV1PromptControl> => {

View on GitHub (pinned to 69428b1f8b)

Solutions

1. Do not request json responseFormat against the pi harness; parse structured data from the agent's final text instead
2. Check harness capability metadata before issuing structured-output turns
3. Switch to a model/provider path (generateObject with a provider model) when structured output is required

Example fix

// before
await session.prompt({
  prompt: 'extract entities',
  responseFormat: { type: 'json' }, // unsupported on pi
});
// after
const result = await session.prompt({ prompt: 'extract entities as JSON' });
const data = JSON.parse(extractText(result));

export function supportsStructuredOutput(harnessId: string): boolean {
  return harnessId !== 'pi';
}
if (opts.responseFormat?.type === 'json' && !supportsStructuredOutput(harnessId)) {
  // route to a provider model or strip responseFormat
}

import { HarnessCapabilityUnsupportedError } from './harness-capability-unsupported-error';
function isCapabilityUnsupported(e: unknown): e is HarnessCapabilityUnsupportedError {
  return HarnessCapabilityUnsupportedError.isInstance(e);
}

try {
  return await session.prompt(opts);
} catch (e) {
  if (isCapabilityUnsupported(e)) {
    return fallbackTextBasedExtraction(opts.prompt); // strip responseFormat
  }
  throw e;
}

When it happens

Trigger: Calling prompt/doPromptTurn on a 'pi' harness session with `responseFormat: { type: 'json' }` (e.g. from generateObject/streamObject over a harness).

Common situations: Sharing a prompt pipeline between model providers and harnesses and hitting the pi harness with an object-generation request; assuming harnesses support the full language-model surface.

Related errors

• Harness 'cline' requires a JSON schema for structured output
• cline: manual compaction is not supported by the standalone
• No object generated: could not parse the response.
• No object generated: response did not match schema.
• No object generated: could not parse the response.

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