[Bug]: Interactive provider onboarding presets the Z.AI/Zhipu general API-plan endpoint, so Coding Plan keys fail the connectivity test and nothing is saved

[SvenMeyer]

Environment

• MiniMax Code (@minimax-ai/code) 0.5.0, npm install, Linux, Node v24.18.0
• Region: outside China (international)
• Z.AI Coding Plan API key

Summary

Adding Z.AI / GLM-5.3 through the interactive provider flow fails with a valid key, and no provider is written to config.yaml. The onboarding preselects the Z.AI general API plan endpoint (https://api.z.ai/api/paas/v4), but a Coding Plan key only works against the coding endpoint (https://api.z.ai/api/coding/paas/v4). The connectivity test fails, and because the flow tests before persisting, nothing is saved.

I had to hand-write the custom_provider block in config.yaml to get GLM-5.3 working.

Root cause

The provider-preset catalog pins a region-specific preferred provider list, but it uses the general API-plan provider ids rather than the coding-plan ones:

packages/local-runtime-v2/src/service/model-system/catalog/provider-presets/provider-presets.service.ts:21-28

const DISABLED_PROVIDER_IDS = new Set([
  'minimax',
  'minimax-cn',
  'minimax-coding-plan',
  'minimax-cn-coding-plan',
]);
const REGION_PINNED_PROVIDER_IDS = {
  cn: ['zhipuai', 'deepseek', 'moonshotai-cn', 'openai', 'anthropic'],
  en: ['zai', 'deepseek', 'moonshotai', 'openai', 'anthropic'],
} as const;

models.dev (the source of these presets) exposes four relevant providers, and mcode's cached snapshot contains all four:

provider id	base URL	plan	region
zai	https://api.z.ai/api/paas/v4	general API	international
zai-coding-plan	https://api.z.ai/api/coding/paas/v4	Coding Plan	international
zhipuai	https://open.bigmodel.cn/api/paas/v4	general API	China
zhipuai-coding-plan	https://open.bigmodel.cn/api/coding/paas/v4	Coding Plan	China

REGION_PINNED_PROVIDER_IDS only pins zai (international) / zhipuai (China). Pinned ids are sorted to the front, so the top entry in the picker is "Z.AI" → the general endpoint. The coding-plan presets are present but buried below it, and the labels ("Z.AI" vs "Z.AI Coding Plan") do not make the endpoint difference obvious.

Region detection itself works (cn → bigmodel, en → api.z.ai); the problem is that it selects the general plan, not the coding plan.

Reproduction

1. Outside China, with a Z.AI Coding Plan key, open /provider (or run mcode provider) and pick the top Z.AI preset.
2. Enter the (valid) Coding Plan key and model glm-5.3.
3. The connectivity test fails and no custom_provider entry is written to ~/.minimax/config.yaml.

Verified with curl using the same key:

• POST https://api.z.ai/api/paas/v4/chat/completions (general) → 429

  {"error":{"code":"1113","message":"Insufficient balance or no resource package. Please recharge."}}

• POST https://api.z.ai/api/coding/paas/v4/chat/completions (coding) → 200

So the test fails purely because it targets the wrong plan's endpoint, not because the key is wrong.

Expected behavior

• Include the coding-plan presets in the region-pinned lists, e.g.:

  cn: ['zhipuai-coding-plan', 'zhipuai', ...],
  en: ['zai-coding-plan', 'zai', ...],

  and label them clearly ("Z.AI Coding Plan" vs "Z.AI API").
• Better: auto-detect. When the connectivity test against the general endpoint returns 401/429/"insufficient balance" for a zai/zhipuai key, retry once against the matching coding endpoint and save that on success. Both endpoints use the same bearer-token shape, so this is cheap and removes the guesswork for the common case (coding plans are the plan most users buy).
• UX: today the failure leaves no config entry and the reason is not stated. Either save the candidate first and mark it unverified, or say explicitly that nothing was saved and that the endpoint likely does not match the plan (see also mcode provider add --use fails with "Test the saved provider configuration" but saves nothing #157).

Notes

• models.dev's env var for these providers is ZHIPU_API_KEY, not ZAI_API_KEY, which is another onboarding gotcha for Z.AI users.
• Inconsistency worth reconciling: mcode's bundled model catalog maps the zai provider id to the coding URL (https://api.z.ai/api/coding/paas/v4) and zai-coding-cn to the bigmodel coding URL, while the BYOK provider-preset flow maps zai to the general URL. The same id means different endpoints depending on the surface.
• GLM-5.3 is present in all four models.dev presets, so this is purely an endpoint/selection problem, not a missing-model problem.

[SvenMeyer]

Follow-up: the same provider id zai maps to two different endpoints in the same binary

While tracing why the interactive add failed, I found mcode ships two model catalogs that disagree about what zai means:

1. BYOK provider presets (models.dev) — packages/local-runtime-v2/src/service/model-system/catalog/provider-presets/provider-presets.service.ts. This is the catalog the interactive add-provider picker reads. zai → https://api.z.ai/api/paas/v4 (general API plan). This is the one that fails for Coding Plan keys.

2. Vendored pi-mono registry — third_party/pi-mono/packages/ai/src/models.generated.ts:17083. zai → https://api.z.ai/api/coding/paas/v4 (Coding Plan), and zai-coding-cn → https://open.bigmodel.cn/api/coding/paas/v4.

So the id zai resolves to the general endpoint in the onboarding path and to the coding endpoint in the vendored registry. The vendored registry also has no glm-5.3 entry at all (its zai block only lists glm-4.5-air, glm-4.7, glm-5-turbo, glm-5.1, glm-5v-turbo), which is why the picker fell through to the models.dev preset that does list glm-5.3.

Concrete impact: a user with a valid Coding Plan key picks the top "Z.AI" preset, the connectivity test hits the general endpoint and gets

{"error":{"code":"1113","message":"Insufficient balance or no resource package. Please recharge."}}

and, because the flow tests before persisting (#157), nothing is written to config.yaml. The same key against the coding endpoint returns 200.

Suggested fix (beyond the region-pinned list change in the description)

• Make the two catalogs agree on what zai/zhipuai mean, or rename the BYOK presets to make the plan explicit (zai-api vs zai-coding-plan).
• Prefer the coding-plan endpoint for the region-pinned entries — that is the plan most users buy — while keeping the general API plan available but clearly labelled.
• Add glm-5.3 (and glm-5.3-highspeed / glm-5.3-flash) to whichever catalog the picker actually uses.

Evidence

models.dev snapshot contains all four presets, each with glm-5.3:

provider id	base URL
zai	https://api.z.ai/api/paas/v4
zai-coding-plan	https://api.z.ai/api/coding/paas/v4
zhipuai	https://open.bigmodel.cn/api/paas/v4
zhipuai-coding-plan	https://open.bigmodel.cn/api/coding/paas/v4

The bundled/vendored registry (models.generated.ts) maps zai to the coding URL of the first row and zai-coding-cn to the coding URL of the third, with no glm-5.3.

[hetaoBackend]

This was generated by AI during triage.

Confirmed as a preset-catalog gap: the interactive onboarding pins the Z.AI general API-plan endpoint (/api/paas/v4), and a Coding Plan key legitimately fails connectivity there — then nothing persists because the flow tests before saving.

Two fixes, both agreed:

1. offer a Coding Plan preset variant (or make the base URL editable before the connectivity test);
2. on connectivity failure, offer save-anyway / edit-and-retry instead of discarding all input.

Your hand-written custom_provider block is the correct workaround for now (companion issue #258 covers the token-counter fallout of that base URL). Thanks for both reports.

[hetaoBackend]

This update was prepared with AI assistance and checked against the merged PR.

Fixed in #272, now merged into main. The local default ordering prefers the regional Coding Plan preset, general-plan presets are explicitly labelled, and onboarding shows the endpoint with Ctrl+E editing before testing or after failure. A failed test keeps the draft for edit-and-retry and explicitly says nothing was saved; there is no automatic endpoint fallback or save-anyway behavior.

The interactive entry point is /model → + Add 3rd-party provider…. Saved custom-provider requests use the explicitly configured URL. The current bundled snapshot already contains GLM-5.3, so no vendored catalog changes were needed.

Focused tests, full local pnpm verify, and Linux/macOS CI passed. Offline built-CLI checks covered the picker and persisted endpoint/inference path; real Z.AI/Zhipu credentials were not tested. This issue is already closed by the merge. Availability in an installed release has not been verified; please retest with a build containing #272. Thanks for the detailed report.