vercel/ai · error · HarnessCapabilityUnsupportedError

Harness 'cline' cannot require structured output with the op

Error message

Harness 'cline' cannot require structured output with the openai-codex-cli provider because that provider does not expose external tools.

What it means

Cline implements required structured output through its tool mechanism, but the openai-codex-cli provider does not expose external tools to the harness. Combining responseFormat.type === 'json' with a model whose providerId is 'openai-codex-cli' therefore cannot be honored, and a HarnessCapabilityUnsupportedError is thrown. This is a hard provider capability limitation, not a configuration typo.

Source

Thrown at packages/harness-cline/src/cline-session.ts:596

    const userTools = turnOpts.tools;
    const skillsRuntime = createClineSkillsRuntime({
      skills: turnOpts.skills,
    });
    if (
      turnOpts.responseFormat?.type === 'json' &&
      turnOpts.responseFormat.schema == null
    ) {
      throw new HarnessCapabilityUnsupportedError({
        message:
          "Harness 'cline' requires a JSON schema for structured output.",
        harnessId: HARNESS_ID,
      });
    }
    if (
      turnOpts.responseFormat?.type === 'json' &&
      agentModel.providerId === 'openai-codex-cli'
    ) {
      throw new HarnessCapabilityUnsupportedError({
        message:
          "Harness 'cline' cannot require structured output with the openai-codex-cli provider because that provider does not expose external tools.",
        harnessId: HARNESS_ID,
      });
    }

    if (turnOpts.model != null && turnOpts.model !== activeModelId) {
      activeModelId = turnOpts.model;
      agentModel = createClineAgentModel({
        settings: input.settings,
        clientApp: input.clientApp,
        modelId: activeModelId,
      });
    }

    const signature = JSON.stringify({
      modelId: activeModelId,
      tools: userTools,

View on GitHub (pinned to 69428b1f8b)

Solutions

1. Use a provider that exposes external tools when you need required JSON output (or run the same workflow against a different agentModel).
2. Remove the required responseFormat for codex-cli runs and instead instruct the model to emit JSON in the prompt, then parse and validate with safeParseJSON.
3. Feature-detect by providerId in your calling code and choose the structured-output strategy per provider.

Example fix

// before
await session.prompt({ text, responseFormat: { type: 'json', schema } }); // codex-cli model
// after
if (agentModel.providerId === 'openai-codex-cli') {
  const { text } = await session.prompt({ text: `${text}\nRespond with only JSON matching: ${JSON.stringify(schema)}` });
  const data = safeParseJSON({ text });
} else {
  await session.prompt({ text, responseFormat: { type: 'json', schema } });
}

function supportsRequiredJsonOutput(providerId: string): boolean {
  return providerId !== 'openai-codex-cli';
}
const useStructured = turnOpts.responseFormat?.type === 'json' && supportsRequiredJsonOutput(agentModel.providerId);

try {
  await session.prompt({ ...opts, responseFormat });
} catch (e) {
  if (HarnessCapabilityUnsupportedError.isInstance(e) && e.message.includes('openai-codex-cli')) {
    // fallback: prompt-instructed JSON + safeParseJSON validation
    await session.prompt({ ...opts, responseFormat: undefined });
  } else throw e;
}

When it happens

Trigger: Running a Cline session with agentModel.providerId === 'openai-codex-cli' and calling prompt with responseFormat: { type: 'json', schema: ... } that requires structured output enforcement.

Common situations: Switching a structured-output workflow from a tool-capable provider (e.g. anthropic, openai) to the codex CLI provider without removing or relaxing responseFormat; building provider-agnostic code that always sets responseFormat regardless of model.

Related errors

• Harness 'cline' requires a JSON schema for structured output
• No object generated: could not parse the response.
• No object generated: response did not match schema.
• No object generated: could not parse the response.
• No object generated: response did not match schema.

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