Skip to content

config: variants documented as array but schema requires object — provider silently dropped #53744

Open

Description

@3marcin

Summary

The models doc shows model variants as an array of { id, settings }
objects, but the published config schema requires variants to be an
object keyed by variant ID. Config following the documented array form
fails schema validation, and the failure is silent: the entire provider
is dropped from the model list with no error or warning at config load.

Environment

  • opencode version: v2.0.24
  • OS: Darwin 25.6.0 (arm64, Apple M-series)
  • Terminal: Ghostty (TERM_PROGRAM=ghostty, COLORTERM=truecolor)
  • Shell: /bin/zsh
  • Install/channel: latest
  • Active plugins: superpowers (project config, bare npm name), superpowers@git+https://github.com/obra/superpowers.git (global config)

Reproduction

  1. Configure a custom OpenAI-compatible provider, copying the documented
    variants array form from the models guide (https://opencode.ai/v2/docs/models, "Variants" section):

    {
      "$schema": "https://opencode.ai/config.json",
      "model": "local/some-model",
      "providers": {
        "local": {
          "package": "@opencode/ai/providers/openai-compatible",
          "settings": { "baseURL": "http://127.0.0.1:8000/v1" },
          "models": {
            "some-model": {
              "limit": { "context": 1000, "output": 1000 },
              // Exactly as documented in the "Variants" section:
              "variants": [
                { "id": "low", "settings": { "reasoningEffort": "low" } },
                { "id": "high", "settings": { "reasoningEffort": "high" } }
              ]
            }
          }
        }
      }
    }
  2. Start OpenCode (or open /models in the TUI).

Expected Behavior

The provider's model appears in the model selector with #low / #high
variants selectable, matching the documented example.

Actual Behavior

  • No error or warning is reported for the config.
  • The provider's model is absent from the model selector; the provider
    appears to have been dropped entirely.
  • Starting a session on that model fails with:
    Unsupported package for local/some-model:

Replacing the array with the object form resolves it immediately:

"variants": {
  "low":  { "settings": { "reasoningEffort": "low" } },
  "high": { "settings": { "reasoningEffort": "high" } }
}

Additional Context

  • The published schema (https://opencode.ai/config.json) defines the model
    variants field as {"type": "object", "additionalProperties": {...}} —
    i.e. a map of variant ID → config — while the models guide shows an array.
    The two official sources contradict each other; one of them needs fixing.
  • The more dangerous part is the silent failure mode: an invalid variants
    shape drops the whole provider with no diagnostic, so the user sees only
    "model missing" / "unsupported package" and has no hint to look at the
    config. A config-validation error (or a warning naming the offending field)
    would make this tractable.
  • Consistently reproducible (not intermittent).

Activity

  1. opencode-agent commented on Oct 7, 2026

    @opencode-agent
    Contributor

    Thanks for the detailed report. I reproduced this on v2.0.24, but in my tests the direction was reversed:

    • The array form from the models guide ("variants": [{ "id": "low", "settings": { ... } }, ...]) worked. The model showed up in opencode2 models and /models.
    • The object form ("variants": { "low": { "settings": { ... } } }) caused the whole local provider to be dropped. It didn't show up in /models, and the only trace was a warning in the log file (~/.local/share/opencode/log/opencode.log): configuration normalization diagnostic ... path=$.providers.local kind=invalid. That warning doesn't mention variants, and nothing is shown in the UI.

    The contradiction you found is real. https://opencode.ai/config.json currently serves the v1 schema, where variants is an object map. The v2 runtime expects the array form that the docs show. So an editor validating against that $schema points you to the shape v2 rejects. Related: #43748.

    The second problem you raised is also confirmed: an invalid variants shape silently drops the entire provider, with no diagnostic that names the field.

    If the array form still fails for you, please share the exact providers block that fails, plus the matching configuration normalization diagnostic lines from that log file. You can reply here, or edit the issue and leave a comment saying you've updated it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions