fix: detect model-not-supported errors from provider response body (#208) by konard · Pull Request #209 · link-assistant/agent

konard · 2026-03-03T17:30:50Z

Summary

Fixes #208 — Agent CLI was not able to finish its work due to a model that was removed from the OpenCode provider catalog.

Root Cause

The solve tool was invoked with --model kimi-k2.5-free. The agent resolved the model from the local cache (stale data) and sent a prompt to the OpenCode API. The provider responded with:

HTTP 401 + {"type":"error","error":{"type":"ModelError","message":"Model kimi-k2.5-free not supported"}}

The problem: OpenCode uses HTTP 401 for "model not supported" instead of the semantically correct 400/404. This makes the error look identical to a real authentication failure, producing confusing diagnostics.

The full root cause analysis and 1920-line log are documented in docs/case-studies/issue-208/README.md.

Fix

Added SessionProcessor.isModelNotSupportedError() in js/src/session/processor.ts which:

Parses the API response body to detect {"type":"ModelError",...} patterns from OpenCode/OpenRouter
Detects both nested format (error.error.type === "ModelError") and flat format (error.type === "ModelError")
Falls back to text pattern matching for non-JSON responses

When detected, a dedicated log.error() entry is emitted that:

Clearly labels the error as a model-availability issue, NOT an auth error
Includes providerID, modelID, statusCode, and the full response body
Suggests using --model <provider>/<model-id> to specify an alternative
Links to the case study (issue Agent CLI was not able to finish its work #208) for further investigation

Documentation Update

Updated all documentation and code defaults to reflect the current 3 free models on OpenCode (per opencode.ai/docs/zen/), in order of recommendation:

Model	Model ID	Notes
MiniMax M2.5 Free	`opencode/minimax-m2.5-free`	Recommended (default) — strong general-purpose performance
GPT 5 Nano	`opencode/gpt-5-nano`	Reliable OpenAI-powered free option
Big Pickle	`opencode/big-pickle`	Stealth model, free during evaluation

Before vs. After

Before — logs only showed a generic API error that looked like auth failure:

{"message": "process", "error": {"name": "APIError", "data": {"statusCode": 401, "isRetryable": false}}}

After — a dedicated diagnostic log entry makes the root cause clear:

{
  "level": "error",
  "service": "session.processor",
  "message": "model not supported by provider — this is NOT an auth error",
  "hint": "The model was found in the local cache but the provider rejected it. The model may have been removed or is temporarily unavailable.",
  "providerID": "opencode",
  "modelID": "kimi-k2.5-free",
  "statusCode": 401,
  "responseBody": "{\"type\":\"error\",\"error\":{\"type\":\"ModelError\",\"message\":\"Model kimi-k2.5-free not supported\"}}",
  "suggestion": "Try a different model or check the provider status. Use --model <provider>/<model-id> to specify an alternative.",
  "issue": "https://github.com/link-assistant/agent/issues/208"
}

Changes

js/src/session/processor.ts: Add isModelNotSupportedError() + diagnostic log for model-not-supported 401 errors
js/tests/model-not-supported.test.ts: 11 unit tests
js/experiments/test-model-error-detection.ts: Experiment script
js/.changeset/fix-model-not-supported-detection.md: Changeset for patch release
docs/case-studies/issue-208/README.md: Complete case study + documentation updates section
docs/case-studies/issue-208/solution-draft-log.txt: Full 1920-line log
FREE_MODELS.md, MODELS.md, README.md, EXAMPLES.md, js/README.md, rust/README.md: Updated free model lists — removed kimi-k2.5-free, set minimax-m2.5-free as new recommended default
js/src/provider/provider.ts: Removed kimi-k2.5-free from priority arrays; minimax-m2.5-free is now the top OpenCode free model
js/src/tool/task.ts: Updated hardcoded fallback default from kimi-k2.5-free to minimax-m2.5-free
rust/src/cli.rs: Updated default model from kimi-k2.5-free to minimax-m2.5-free

Test Plan

11 new unit tests pass (model-not-supported.test.ts)
Experiment script demonstrates all 5 scenarios correctly
Full test suite: pre-existing failures unchanged (unrelated to this PR)
Pre-commit hooks pass (prettier, lint)
Real-world validation via live API test

Adding CLAUDE.md with task information for AI processing. This file will be removed when the task is complete. Issue: #208

) When the OpenCode provider removes or restricts a model, the API returns HTTP 401 with a body like: {"type":"error","error":{"type":"ModelError","message":"Model X not supported"}} Without special handling this looks identical to an authentication failure (both are HTTP 401), making root-cause diagnosis very confusing. Adds SessionProcessor.isModelNotSupportedError() which parses the response body and detects the ModelError pattern from OpenCode/OpenRouter. When detected, a dedicated log.error() entry is emitted that: - Labels the error as a model-availability issue, NOT an auth error - Includes providerID, modelID, statusCode, and the full response body - Suggests using --model <provider>/<model-id> to specify an alternative - Links to the case study (issue #208) for further investigation Also adds: - 11 unit tests covering nested/flat JSON formats, real auth errors (no false positives), plain-text fallback detection, and edge cases - Experiment script demonstrating all detection scenarios - Case study analysis in docs/case-studies/issue-208/ with the full 1920-line log from the failing run, timeline, root cause analysis, and 5 proposed solutions Fixes #208 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

This reverts commit 0f06f23.

konard · 2026-03-03T17:51:00Z

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

Public pricing estimate: $3.450514
Calculated by Anthropic: $4.121174 USD
Difference: $0.670660 (+19.44%)
📎 Log file uploaded as Gist (9365KB)
🔗 View complete solution draft log

Now working session is ended, feel free to review and add any feedback on the solution draft.

konard · 2026-03-03T17:54:18Z

🔄 Auto-restart triggered (attempt 1)

Reason: CI failures detected

Starting new session to address the issues.

Auto-restart-until-mergeable mode is active. Will continue until PR becomes mergeable.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

konard · 2026-03-03T17:58:09Z

🔄 Auto-restart-until-mergeable Log (iteration 1)

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

Public pricing estimate: $0.334776
Calculated by Anthropic: $0.289344 USD
Difference: $-0.045432 (-13.57%)
📎 Log file uploaded as Gist (10053KB)
🔗 View complete solution draft log

Now working session is ended, feel free to review and add any feedback on the solution draft.

konard · 2026-03-03T17:59:15Z

✅ Ready to merge

This pull request is now ready to be merged:

All CI checks have passed
No merge conflicts
No pending changes

Monitored by hive-mind with --auto-restart-until-mergeable flag

konard · 2026-03-03T18:29:19Z

Also update our docs, to reflect that now only 3 models are free:

Big Pickle
MiniMax M2.5 Free
GPT 5 Nano

https://opencode.ai/docs/zen/

konard · 2026-03-03T18:29:57Z

🤖 AI Work Session Started

Starting automated work session at 2026-03-03T18:29:55.245Z

The PR has been converted to draft mode while work is in progress.

This comment marks the beginning of an AI work session. Please wait for the session to finish, and provide your feedback.

… to big-pickle (#208) `opencode/kimi-k2.5-free` was removed from the OpenCode Zen provider (see case study #208). Update all docs and code to reflect the current 3 free models: big-pickle, minimax-m2.5-free, gpt-5-nano. Changes: - FREE_MODELS.md: remove kimi-k2.5-free from active table, add to discontinued; set big-pickle as recommended default - MODELS.md: same table updates + update default model note - README.md, EXAMPLES.md, js/README.md, rust/README.md: replace all opencode/kimi-k2.5-free example usages with opencode/big-pickle - js/src/provider/provider.ts: remove kimi-k2.5-free from priority arrays (both small-model selection and default model sort order) - js/src/tool/task.ts: update hardcoded fallback default from kimi-k2.5-free to big-pickle - docs/case-studies/issue-208/README.md: add Documentation Updates section summarising the changes made as a result of this case study Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

konard · 2026-03-03T18:44:37Z

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

Public pricing estimate: $2.889946
Calculated by Anthropic: $2.472318 USD
Difference: $-0.417628 (-14.45%)
📎 Log file uploaded as Gist (2553KB)
🔗 View complete solution draft log

Now working session is ended, feel free to review and add any feedback on the solution draft.

konard · 2026-03-04T10:13:10Z

opencode/minimax-m2.5-free

This model should be default now.

GPT 5 Nano should go next (in docs and so on), and Big Pickle last as it is the worst from these 3.

konard · 2026-03-04T10:13:45Z

🤖 AI Work Session Started

Starting automated work session at 2026-03-04T10:13:43.442Z

The PR has been converted to draft mode while work is in progress.

This comment marks the beginning of an AI work session. Please wait for the session to finish, and provide your feedback.

#208) Change default free model from big-pickle to minimax-m2.5-free (best of the 3 free OpenCode Zen models), update recommendation order to: 1. minimax-m2.5-free (new default — best quality) 2. gpt-5-nano (second) 3. big-pickle (last — worst of the 3) Also fixes Rust CLI default which still had the removed kimi-k2.5-free. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

konard · 2026-03-04T10:23:57Z

🤖 Solution Draft Log

This log file contains the complete execution trace of the AI solution draft process.

💰 Cost estimation:

Public pricing estimate: $2.598564
Calculated by Anthropic: $2.190280 USD
Difference: $-0.408284 (-15.71%)
📎 Log file uploaded as Gist (2625KB)
🔗 View complete solution draft log

Now working session is ended, feel free to review and add any feedback on the solution draft.

Initial commit with task details

0f06f23

Adding CLAUDE.md with task information for AI processing. This file will be removed when the task is complete. Issue: #208

konard self-assigned this Mar 3, 2026

konard changed the title ~~[WIP] Agent CLI was not able to finish its work~~ fix: detect model-not-supported errors from provider response body (#208) Mar 3, 2026

konard marked this pull request as ready for review March 3, 2026 17:50

Revert "Initial commit with task details"

06189af

This reverts commit 0f06f23.

style: fix Prettier formatting in experiments and tests

419b6bf

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

konard marked this pull request as draft March 3, 2026 18:29

konard marked this pull request as ready for review March 3, 2026 18:43

konard marked this pull request as draft March 4, 2026 10:13

konard marked this pull request as ready for review March 4, 2026 10:23

konard merged commit c7bb795 into main Mar 4, 2026
15 checks passed

This was referenced Mar 4, 2026

fix: update default agent model to minimax-m2.5-free (Issue #1391) link-assistant/hive-mind#1392

Merged

refactor: centralize DEFAULT_MODEL constant, fix remaining kimi-k2.5-free references (#208) #210

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

fix: detect model-not-supported errors from provider response body (#208)#209

fix: detect model-not-supported errors from provider response body (#208)#209
konard merged 6 commits intomainfrom
issue-208-1518358cc8fc

konard commented Mar 3, 2026 •

edited

Loading

Uh oh!

konard commented Mar 3, 2026

Uh oh!

konard commented Mar 3, 2026

Uh oh!

konard commented Mar 3, 2026

Uh oh!

konard commented Mar 3, 2026

Uh oh!

konard commented Mar 3, 2026

Uh oh!

konard commented Mar 3, 2026

Uh oh!

konard commented Mar 3, 2026

Uh oh!

konard commented Mar 4, 2026

Uh oh!

konard commented Mar 4, 2026

Uh oh!

konard commented Mar 4, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Conversation

konard commented Mar 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Root Cause

Fix

Documentation Update

Before vs. After

Changes

Test Plan

Uh oh!

konard commented Mar 3, 2026

🤖 Solution Draft Log

Uh oh!

konard commented Mar 3, 2026

🔄 Auto-restart triggered (attempt 1)

Uh oh!

konard commented Mar 3, 2026

🔄 Auto-restart-until-mergeable Log (iteration 1)

Uh oh!

konard commented Mar 3, 2026

✅ Ready to merge

Uh oh!

konard commented Mar 3, 2026

Uh oh!

konard commented Mar 3, 2026

Uh oh!

konard commented Mar 3, 2026

🤖 Solution Draft Log

Uh oh!

konard commented Mar 4, 2026

Uh oh!

konard commented Mar 4, 2026

Uh oh!

konard commented Mar 4, 2026

🤖 Solution Draft Log

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

konard commented Mar 3, 2026 •

edited

Loading