OpenAI-compatible chat providers fail when the endpoint requires max_completion_tokens instead of max_tokens

[VarunMotiyani]

Description

The generic OpenAI-compatible chat protocol (packages/llm/src/protocols/openai-chat.ts) always sends max_tokens in the request body. Some OpenAI-compatible deployments reject this and require max_completion_tokens instead, returning a standard error like:

{
  "error": {
    "message": "Unsupported parameter: 'max_tokens' is not supported with this model. Use 'max_completion_tokens' instead.",
    "type": "invalid_request_error",
    "param": "max_tokens",
    "code": "unsupported_parameter"
  }
}

Right now this makes the provider unusable out of the box — the only workaround is writing a custom plugin that intercepts chat.params and rewrites the field manually.

This isn't a one-off case: OpenCode already ships two provider-specific patches for the same underlying issue (Cerebras: packages/core/src/plugin/provider/cerebras.ts, Snowflake Cortex: packages/core/src/plugin/provider/snowflake-cortex.ts, both rewriting max_tokens → max_completion_tokens). Those are hardcoded to specific npm packages / provider IDs, so they don't help anyone using a custom openai-compatible provider pointed at a gateway with this same requirement.

Plugins

None required for this fix — it replaces the need for a custom chat.params plugin.

OpenCode version

1.18.23

Steps to reproduce

1. Configure a custom provider using @ai-sdk/openai-compatible pointed at any OpenAI-compatible endpoint that rejects max_tokens and requires max_completion_tokens.
2. Send a chat request through that provider.
3. Request fails instead of retrying with the corrected field.

Screenshot and/or share link

No response

Operating System

macOS 26.6.2

Terminal

Terminal

[github-actions]

This issue might be a duplicate of existing issues. Please check:

• Unsupported parameter: 'max_tokens' is not supported with this model. Use 'max_completion_tokens' instead. #37964: Same error message — max_tokens rejected, requires max_completion_tokens instead
• openai-compatible adapter sends max_tokens to GPT-5/o-series reasoning models that require max_completion_tokens #25096: openai-compatible adapter sends max_tokens to models that require max_completion_tokens
• OpenAI-compatible GPT-5.x models still send max_tokens on AI SDK fallback path #40885: OpenAI-compatible GPT-5.x models still send max_tokens on AI SDK fallback path
• cloudflare-ai-gateway: Azure GPT-5.x models fail (max_tokens vs max_completion_tokens); per-model compat not honored #32776: Azure GPT-5.x models fail due to max_tokens vs max_completion_tokens; per-model compat not honored
• Azure GPT-5 model: "max_tokens" parameter not supported, need "max_completion_tokens" instead #22623: Azure GPT-5 model: max_tokens parameter not supported, need max_completion_tokens instead

If your issue is distinct (e.g. it specifically affects custom openai-compatible gateway configs rather than named providers), please clarify what makes it different from the above.

[VarunMotiyani]

The duplicate check — this overlaps with #25096, #32776, #40885, #22623 on symptom (all are max_tokens vs max_completion_tokens), but those are scoped to specific providers/model families (Azure, cloudflare-ai-gateway, gpt-5.x by name). This report is about the general case: any @ai-sdk/openai-compatible provider pointed at a gateway that requires max_completion_tokens, regardless of model name or which gateway it is. Happy to have this closed in favor of one of those if maintainers prefer to track it there instead.

Dug into this a bit more before proposing a fix, since I initially assumed there was one request path — there are actually two:

• Native runtime (packages/llm, opt-in via experimentalNativeLlm) — not the default, most users won't hit this.
• AI SDK runtime (default) — calls streamText() from Vercel's ai package, which builds the request via @ai-sdk/openai-compatible directly. This is the path everyone in the linked issues is actually hitting, and it always sends max_tokens with no way to configure otherwise.

Two things ruled out:

• A blanket rewrite to max_completion_tokens for all openai-compatible providers — unsafe, since plenty of self-hosted OpenAI-compatible servers only accept max_tokens and would break.
• Matching on model name (e.g. gpt-5*) — works today but is brittle for future model families and doesn't help custom-named providers behind a gateway (like this report).

Proposed fix: an explicit, opt-in compatibility flag on the model config, e.g.

"models": {
  "gpt-5.4": {
    "compatibility": { "maxTokensField": "max_completion_tokens" }
  }
}

honored by the default request-prep path before streamText is called. This isn't a new concept — packages/llm/src/schema/options.ts already has ModelCompatibility with a toolSchema field for this exact kind of "known upstream quirk," just currently scoped to the native runtime only. This would widen that pattern to the default path and add the token-field case.

Implementation-wise, this doesn't need new plugin API either — @ai-sdk/openai-compatible already lets provider options pass through for any key it doesn't recognize as standard, which is the same mechanism the existing Cerebras/Snowflake Cortex plugins use to do this rewrite today. This would just be that same technique, driven by the config flag instead of a hardcoded provider check.

[VarunMotiyani]

Hey @neriousy — saw you got assigned. Have a fix ready on my end for the design I proposed above (opt-in compatibility.max_tokens_field on model config). Should I open the PR, or are you already working on something for this?

[throny]

Another variant of this issue: the Responses API has renamed the parameter again from max_completion_tokens to max_output_tokens. OpenCode 1.18.32+ sends max_completion_tokens but newer endpoints implementing the latest spec reject it with:

400 Unsupported parameter: 'max_completion_tokens'.
In the Responses API, this parameter has moved to 'max_output_tokens'.

This affects any custom openai-compatible provider pointed at an endpoint that implements the newest Responses API spec. The provider needs to send max_output_tokens instead.

Config used:

• Provider: @opencode/ai/providers/openai-compatible
• Model: gpt-6-luna (reasoning model)
• Endpoint: custom gateway implementing the latest Responses API

The fix should handle all three parameter names (max_tokens, max_completion_tokens, max_output_tokens) with automatic fallback when the API rejects the parameter.