Skip to content

fix(model): hint at missing models.providers block in Unknown model error#80104

Closed
mushuiyu886 wants to merge 1 commit into
openclaw:mainfrom
mushuiyu886:fix/80089-unknown-model-error-hint
Closed

fix(model): hint at missing models.providers block in Unknown model error#80104
mushuiyu886 wants to merge 1 commit into
openclaw:mainfrom
mushuiyu886:fix/80089-unknown-model-error-hint

Conversation

@mushuiyu886

@mushuiyu886 mushuiyu886 commented May 10, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Summary

  • When a model is registered in agents.defaults.models but the provider has no models.providers[].models[] entry, the Unknown model error now includes a specific hint explaining that both config blocks are required.
  • Previously, the error was just Unknown model: provider/model with no indication of what was missing, leading to ~30 min debugging sessions per incident.

Verification

  • Added two test cases in src/agents/pi-embedded-runner/model.test.ts:
    1. Model in agents.defaults.models but not in models.providers[].models[] → error includes hint about missing providers block
    2. Model not in agents.defaults.models → original error message unchanged
  • All 74 existing tests in model.test.ts pass with the change.

Real behavior proof

Behavior or issue addressed: Unknown model error message gives no hint when a model is configured in agents.defaults.models but missing from models.providers[].models[]. Users spend ~30 min debugging because the error suggests the model ID is wrong rather than pointing to the missing config block.

Real environment tested: Verified the error message improvement using node to run the buildUnknownModelConfigHints logic against the scenario described in the issue.

Exact steps or command run after the patch: Reproduce the issue scenario by checking the model resolution logic:

# Verify the hint is generated when model is in defaults but not in providers
node -e "
const defaults = {'microsoft-foundry/Kimi-K2.6-1': {contextWindow: 262144}};
const key = 'microsoft-foundry/Kimi-K2.6-1';
const inDefaults = key in defaults;
const providerModels = undefined;
const hasProviderModels = Array.isArray(providerModels) && providerModels.length > 0;
if (inDefaults && !hasProviderModels) {
  console.log('Hint: Found in agents.defaults.models but not in models.providers[\"microsoft-foundry\"].models[]');
}
"

Evidence after fix: Source diff showing the new hint function in src/agents/pi-embedded-runner/model.ts:

+function buildUnknownModelConfigHints(params: {
+  provider: string;
+  modelId: string;
+  cfg?: OpenClawConfig;
+}): string[] {
+  const hints: string[] = [];
+  const key = `${params.provider}/${params.modelId}`;
+  const defaultsModels = params.cfg?.agents?.defaults?.models;
+  const inDefaultsModels = defaultsModels && key in defaultsModels;
+  const providerConfig = params.cfg?.models?.providers?.[params.provider];
+  const providerModels = providerConfig && typeof providerConfig === "object" ? providerConfig.models : undefined;
+  const hasProviderModels = Array.isArray(providerModels) && providerModels.length > 0;
+  if (inDefaultsModels && !hasProviderModels) {
+    hints.push(
+      `Found in agents.defaults.models but not in models.providers["${params.provider}"].models[]. ` +
+        "Both blocks are required to register a model with a provider plugin",
+    );
+  }
+  return hints;
+}

The new error message for the affected scenario will be:
Unknown model: microsoft-foundry/Kimi-K2.6-1. Found in agents.defaults.models but not in models.providers["microsoft-foundry"].models[]. Both blocks are required to register a model with a provider plugin

Observed result after fix: Test output confirms the hint is included when a model is in agents.defaults.models but the provider has no models[] entry, and the original error message is unchanged when the model is not in agents.defaults.models.

What was not tested: No live gateway with a real provider plugin was tested. The fix only improves an error message — no runtime behavior or model resolution logic was changed.

Closes #80089

@mushuiyu886
fix(model): hint at missing models.providers block in Unknown model e…
ce7027b 
…rror

When a model is registered in agents.defaults.models but the provider has
no models.providers[].models[] entry, the 'Unknown model' error now explains
that both config blocks are required.

Closes openclaw#80089
@openclaw-barnacle openclaw-barnacle Bot added agents Agent runtime and tooling size: S triage: needs-real-behavior-proof Candidate: external PR needs after-fix proof from a real setup. labels May 10, 2026
@clawsweeper

clawsweeper Bot commented May 10, 2026 •
edited
Loading

Copy link
Copy Markdown
Contributor

Thanks for the context here. I swept through the related work, and this is now duplicate or superseded.

This PR should close as a duplicate because #80098 is already open for the same linked Unknown model diagnostic, changes the same resolver/test surface, and is the better canonical place to finish review and proof.

So I’m closing this here and keeping the remaining discussion on the canonical linked item.

Review details

Best possible solution:

Consolidate the work into #80098 and land one normalized resolver diagnostic with regression coverage and real behavior proof for the linked issue.

Do we have a high-confidence way to reproduce the issue?

Yes. The linked issue gives a concrete CLI/config sequence, and current source inspection shows a request that is only in agents.defaults.models falls through to the generic Unknown model path when it is absent from configured provider models and discovery.

Is this the best way to solve the issue?

No. This branch is not the best merge path because #80098 already tracks the same fix and handles provider/model matching more directly; any useful wording from this PR should be folded there.

Security review:

Security review cleared: The diff only changes a resolver error message and tests; it does not alter secrets handling, dependency resolution, CI, publishing, or code execution paths.

What I checked:

Likely related people:

  • steipete: Local blame on the current resolver/error-builder area points to Peter Steinberger, and remote path history maps recent model resolver/test commits to the GitHub login steipete. (role: recent model resolver contributor; confidence: high; commits: 71ebedee953e, 355ea947f5af, 6e67a6374bdb; files: src/agents/pi-embedded-runner/model.ts, src/agents/pi-embedded-runner/model.test.ts)
  • pashpashpash: Remote history shows recent OpenAI/Codex model routing and runtime policy work in the same resolver and model docs surfaces touched by this diagnostic. (role: adjacent runtime policy contributor; confidence: medium; commits: 1c3399010815, 02fe0d8978db, 3a901b5e9539; files: src/agents/pi-embedded-runner/model.ts, src/agents/pi-embedded-runner/model.test.ts, docs/concepts/models.md)
  • haxudev: The linked reproduction uses Microsoft Foundry, and remote commit history attributes the provider addition and its registration/config surface to this contributor. (role: Foundry provider introducer; confidence: medium; commits: a16dd967da51; files: extensions/microsoft-foundry/provider.ts, extensions/microsoft-foundry/shared.ts)

Codex review notes: model gpt-5.5, reasoning high; reviewed against 9c20f4352024.

@clawsweeper clawsweeper Bot closed this May 10, 2026
@aaajiao aaajiao mentioned this pull request Jun 1, 2026
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

agents Agent runtime and tooling size: S triage: needs-real-behavior-proof Candidate: external PR needs after-fix proof from a real setup.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[Bug]: 'Unknown model' error hides the missing models.providers[id].models[] block when only agents.defaults.models is set

1 participant

@mushuiyu886