Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

fix(errors): name an unsupported model and a wrong-plan key in the hint

Jack Rudenkofa09cb7eb85b
diff --git a/packages/cli/src/handlers/composed-handler.ts b/packages/cli/src/handlers/composed-handler.ts
index 6211eb14..b1d5922a 100644
--- a/packages/cli/src/handlers/composed-handler.ts
+++ b/packages/cli/src/handlers/composed-handler.ts
@@ -36,6 +36,7 @@ import { getBehaviorEngine } from "../behavior/index.js";
import { getLogLevel, log, logStderr, logStructured, truncateContent } from "../logger.js";
import { GeminiThoughtSignatureMiddleware, MiddlewareManager } from "../middleware/index.js";
import { deepMergeParams } from "../model-params.js";
+import { describeSiblingKeys, getProviderByName } from "../providers/provider-definitions.js";
import { isTerminal429 } from "../providers/transport/openai.js";
import {
type OpenAIImageBlock,
@@ -924,7 +925,13 @@ export class ComposedHandler implements ModelHandler {
response.status,
errorText,
this.provider.displayName,
- transportTerminal
+ transportTerminal,
+ // The INTERNAL name, beside the display name: the catalog is keyed by
+ // it, and an auth failure on a vendor with sibling-tier keys needs
+ // that lookup to say which other key exists. A transport whose name
+ // is not a catalog entry (a custom endpoint) simply finds nothing and
+ // gets today's sentence unchanged.
+ this.provider.name
);
let parsedErrorBody: any;
try {
@@ -1726,12 +1733,21 @@ export class ComposedHandler implements ModelHandler {
* heuristics below, which are pattern-matching prose and cannot tell a spent
* plan from a per-minute throttle when the provider phrases both identically.
* `undefined` — every transport without the hook — keeps the original behaviour.
+ *
+ * `providerUid` is the INTERNAL provider name (`ProviderTransport.name`, e.g.
+ * `qwen-token-plan`), not the display name, because it is what the provider
+ * catalog is keyed by. It is optional and every branch below is unchanged
+ * without it: it only lets the auth branch look up whether this vendor ships a
+ * SECOND, non-interchangeable key for another tier (`siblingKeyEnvVars`).
+ * Nothing is inferred from the credential itself — see the branch for why the
+ * key's own bytes are deliberately not read.
*/
export function getRecoveryHint(
status: number,
errorText: string,
providerName: string,
- transportTerminal429?: boolean
+ transportTerminal429?: boolean,
+ providerUid?: string
): string {
const lower = errorText.toLowerCase();
@@ -1806,6 +1822,31 @@ export function getRecoveryHint(
if (hasActionableLink(errorText)) {
return "Provider rejected the request and gave a specific fix — follow the link in the message below.";
}
+ // Reached only when the credential really is the most likely cause. For a
+ // vendor that sells the SAME models under several plans, "check your key"
+ // is still not the whole story: the plans' keys are isolated and rejected
+ // by each other's hosts with a near-identical 401, so "right key, wrong
+ // silo" is at least as likely as "bad key". Measured 2026-09-17 with one
+ // real Alibaba Token Plan key: 200 on `token-plan…`, 401 `invalid access
+ // token or token expired` on `coding-intl…`, 401 `Incorrect API key
+ // provided` on `dashscope-intl…`.
+ //
+ // Driven by `siblingKeyEnvVars`, so it is a property of any vendor that
+ // declares one (`opencode-zen-go` does today) rather than an Alibaba
+ // special case — and the variable names come from the catalog via
+ // `describeSiblingKeys`, the same sentence `describeMissingCredential`
+ // emits, so the two cannot drift into saying different things about one
+ // pair of keys.
+ //
+ // What this deliberately does NOT do is look at the key. A Token Plan key
+ // can match `sk-sp-`, which Alibaba's own Coding Plan docs call their
+ // format, so a prefix hint would confidently mislabel a working
+ // credential. The key's bytes are never read, which also keeps a failed
+ // secret operation out of a status line.
+ const siblingNote = providerUid ? describeSiblingKeys(getProviderByName(providerUid)) : "";
+ if (siblingNote) {
+ return `Check API key / OAuth credentials. This vendor sells several plans whose keys are isolated, so a 401 can also mean the right key on the wrong plan's host.${siblingNote}`;
+ }
return "Check API key / OAuth credentials.";
}
if (status === 404) {
@@ -1831,6 +1872,19 @@ export function getRecoveryHint(
if (isRequestShapeError(errorText)) {
return "Wrong request shape for this endpoint — the provider named the parameter it rejected (see the message below). Nothing was too large; a shorter prompt will not help.";
}
+ // A model the provider does not carry also arrives as a 400 — Alibaba's
+ // silos answer an id outside the plan with a bare `Model not exist`. Same
+ // predicate the 401/403 branch above uses, for the same reason it exists:
+ // one reading of "the MODEL is the problem", so the hint cannot say
+ // something different depending on which status the provider chose.
+ //
+ // Placed AFTER `isRequestShapeError` (a provider that names a parameter has
+ // stated the fact, and a heuristic must not talk over it) and BEFORE the
+ // size test, which is a bare `includes("token")` and would otherwise claim
+ // any model-unsupported body that happens to spell "tokens".
+ if (hasModelUnsupportedWording(errorText)) {
+ return "Model not supported by this provider. Verify model name.";
+ }
if (lower.includes("context") || lower.includes("too long") || lower.includes("token")) {
return "Input too large. Reduce message history or use a larger-context model.";
}
diff --git a/packages/cli/src/handlers/shared/model-unsupported.blackbox.test.ts b/packages/cli/src/handlers/shared/model-unsupported.blackbox.test.ts
new file mode 100644
index 00000000..22d95ca8
--- /dev/null
+++ b/packages/cli/src/handlers/shared/model-unsupported.blackbox.test.ts
@@ -0,0 +1,49 @@
+/**
+ * BLACK-BOX. Written by `gpt-6-astra` from the spec and a body-stripped `.d.ts`,
+ * with no access to this implementation. See
+ * `ai-docs/reports/blackbox-tests-alibaba/blackbox-results.md`.
+ *
+ * DO NOT edit an assertion to make it pass. Its value is that its author had
+ * never read the code; a repaired assertion is a regression test, not evidence.
+ * Adaptation on integration: import path only.
+ */
+import { describe, expect, test } from "bun:test";
+import { useBlackboxEnv } from "../../test-helpers/blackbox-env.js";
+import { hasActionableLink, hasModelUnsupportedWording } from "./model-unsupported.js";
+
+useBlackboxEnv();
+
+describe("unsupported models and invalid keys require different remedies", () => {
+ for (const body of [
+ "Model not exist",
+ JSON.stringify({ error: { message: "Model not exist" } }),
+ "Model deepseek-v4-pro-0813 is not supported",
+ ]) {
+ test(`E1 unsupported wording survives its error envelope: ${body}`, () => {
+ expect(hasModelUnsupportedWording(body)).toBe(true);
+ });
+ }
+ for (const body of [
+ "InvalidApiKey",
+ "invalid access token or token expired",
+ "Incorrect API key provided",
+ ]) {
+ test(`E2 the measured credential rejection is not model exclusion: ${body}`, () => {
+ expect(hasModelUnsupportedWording(body)).toBe(false);
+ });
+ }
+ test("E3 a vendor action URL is recognized so a generic key hint need not contradict it", () => {
+ const body = JSON.stringify({
+ error: {
+ type: "RegionError",
+ message:
+ "The latest version of this model is only available hosted in China and requires explicit opt in: https://opencode.ai/workspace/qa/go",
+ },
+ });
+ expect(hasActionableLink(body)).toBe(true);
+ expect(hasModelUnsupportedWording(body)).toBe(false);
+ });
+ test("E4 a credential error without a link does not pretend to contain an action URL", () => {
+ expect(hasActionableLink("Incorrect API key provided")).toBe(false);
+ });
+});
diff --git a/packages/cli/src/handlers/shared/model-unsupported.ts b/packages/cli/src/handlers/shared/model-unsupported.ts
index e16126e5..fe1f5ace 100644
--- a/packages/cli/src/handlers/shared/model-unsupported.ts
+++ b/packages/cli/src/handlers/shared/model-unsupported.ts
@@ -49,6 +49,18 @@ const UNSUPPORTED_PHRASES = [
"model not found",
"model_not_found",
"unknown model",
+ // Alibaba's wording, and it is NOT a typo on our side: the Token Plan and
+ // PAYG hosts answer an id their silo does not serve with a bare
+ // `400 Model not exist` (measured 2026-09-17; `qwen-alibaba.md` records the
+ // dead end it produced). It matched none of the phrases above — not "model
+ // not found", not "does not exist" — so the one hint claudish could give was
+ // "Request format may be incompatible with provider", which sends the reader
+ // to audit a payload that is fine.
+ //
+ // Recognised for the MESSAGE only. `FallbackHandler.isRetryableError` keeps
+ // its own 400 phrase list and deliberately does not carry this one, so the
+ // chain still stops on it rather than advancing.
+ "model not exist",
"no such model",
] as const;
diff --git a/packages/cli/src/providers/provider-definitions.ts b/packages/cli/src/providers/provider-definitions.ts
index d288d0c1..3ad167a0 100644
--- a/packages/cli/src/providers/provider-definitions.ts
+++ b/packages/cli/src/providers/provider-definitions.ts
@@ -1487,8 +1487,15 @@ export function describeMissingCredential(providerName: string): string {
* is already in the catalog as `apiKeyEnvVar`. A variable no provider claims
* (a rename, a removal) degrades to the bare name instead of asserting a
* provider that no longer exists.
+ *
+ * Exported because the SECOND place a user meets this fact is a 401 — they set
+ * the sibling key, and the vendor's other host rejected it with wording that
+ * attributes nothing (`invalid access token or token expired`). The recovery
+ * hint in `composed-handler.ts` appends this same sentence there, rather than
+ * writing a second one, so the "no key" copy and the "wrong key" copy can never
+ * disagree about which variable belongs to which plan.
*/
-function describeSiblingKeys(def: ProviderDefinition | undefined): string {
+export function describeSiblingKeys(def: ProviderDefinition | undefined): string {
const vars = def?.siblingKeyEnvVars ?? [];
if (vars.length === 0) return "";
const all = getAllProviders();
diff --git a/packages/cli/src/test-helpers/blackbox-env.ts b/packages/cli/src/test-helpers/blackbox-env.ts
new file mode 100644
index 00000000..774df595
--- /dev/null
+++ b/packages/cli/src/test-helpers/blackbox-env.ts
@@ -0,0 +1,114 @@
+/**
+ * Isolation harness for the BLACK-BOX behaviour suite (`*.blackbox.test.ts`).
+ *
+ * Those files were written by an external model that never saw this repository's
+ * implementation — only the spec, the acceptance criteria and `.d.ts` contracts
+ * with every body stripped. This module is the only part of that delivery that
+ * was rewritten on integration, and it was rewritten for one reason: the
+ * original relocated `HOME` and replaced `globalThis.fetch` at MODULE LOAD and
+ * restored them only at `process.once("exit")`.
+ *
+ * That is correct inside a sandbox holding seven files and wrong inside a
+ * 231-file suite. Bun's test runner shares one process across every test file —
+ * the same property that makes `mock.module()` bleed here — so a process-wide
+ * `HOME` swap changes what every LATER file sees, and several modules snapshot
+ * their paths at module scope (`profile-config.ts:18`,
+ * `all-models-cache.ts:102`), so the swap would also be invisible to the very
+ * readers it was meant to redirect. A permanently throwing `fetch` would take
+ * the live-API tests with it.
+ *
+ * So the isolation is FILE-SCOPED: `useBlackboxEnv()` installs in `beforeAll`
+ * and uninstalls in `afterAll`. The writer's two guarantees are kept intact —
+ * no real user state, and a fail-closed network tripwire whose `afterEach`
+ * check catches even an implementation that swallows the rejection.
+ *
+ * Config reads are isolated through the repo's own seam
+ * (`setConfigFileOverride`) rather than through `HOME`, because the module-level
+ * snapshot above means a relocated `HOME` cannot reach `loadConfig()` at all.
+ */
+import { afterAll, afterEach, beforeAll, expect } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+/** A cold, generated HOME. Never the developer's. */
+export const sandboxHome = mkdtempSync(join(tmpdir(), "claudish-blackbox-home-"));
+mkdirSync(join(sandboxHome, ".claudish"), { recursive: true });
+
+/**
+ * The writer's contract also named a variable that switched off an on-disk
+ * store of the dynamic models catalog. It is deliberately NOT here: that store
+ * was deleted in `fe8722e`, and the variable with it.
+ */
+const RELOCATED: Record<string, string> = {
+ HOME: sandboxHome,
+ USERPROFILE: sandboxHome,
+ XDG_CONFIG_HOME: join(sandboxHome, ".config"),
+ CLAUDISH_DISABLE_KEYCHAIN: "1",
+ CLAUDISH_DISABLE_OP: "1",
+};
+
+const saved = new Map<string, string | undefined>();
+let realFetch: typeof globalThis.fetch | null = null;
+const attemptedFetches: string[] = [];
+
+function install(): void {
+ if (realFetch) return;
+ for (const [name, value] of Object.entries(RELOCATED)) {
+ saved.set(name, process.env[name]);
+ process.env[name] = value;
+ }
+ realFetch = globalThis.fetch;
+ const tripwire = async (input: unknown) => {
+ const url =
+ typeof input === "string"
+ ? input
+ : input instanceof URL
+ ? input.href
+ : ((input as { url?: string })?.url ?? "unknown");
+ attemptedFetches.push(`Unexpected network access: ${url}`);
+ throw new Error("Black-box QA forbids network access");
+ };
+ // `preconnect` is a Bun/undici extension on the real `fetch`; carry it over so
+ // the replacement is structurally a `fetch` and nothing downstream throws on a
+ // missing property before the tripwire can record the attempt.
+ tripwire.preconnect = realFetch.preconnect;
+ globalThis.fetch = tripwire as unknown as typeof fetch;
+}
+
+function uninstall(): void {
+ if (!realFetch) return;
+ globalThis.fetch = realFetch;
+ realFetch = null;
+ for (const [name, value] of saved) restoreEnv(name, value);
+ saved.clear();
+}
+
+/**
+ * Install the isolation for the CALLING test file. Call it once, at the top of
+ * the file, before any `describe`.
+ */
+export function useBlackboxEnv(): void {
+ beforeAll(install);
+ afterEach(() => {
+ const attempts = attemptedFetches.splice(0);
+ expect(attempts).toEqual([]);
+ });
+ afterAll(uninstall);
+}
+
+process.once("exit", () => {
+ uninstall();
+ rmSync(sandboxHome, { recursive: true, force: true });
+});
+
+/** A fresh scratch directory under the sandbox HOME. */
+export function scratchDirectory(label: string): string {
+ return mkdtempSync(join(sandboxHome, `${label}-`));
+}
+
+/** Put one environment variable back exactly as it was, absent included. */
+export function restoreEnv(name: string, value: string | undefined): void {
+ if (value === undefined) delete process.env[name];
+ else process.env[name] = value;
+}