How to Fix the “qwen3.8-max isn’t described by this version’s model catalog” Warning in Claude Code CLI

If you run non-standard, custom, or self-hosted LLM endpoints (such as qwen3.8-max routed through a proxy or an OpenAI-compatible gateway) inside Claude Code CLI, your terminal will throw a long, persistent warning on startup:

"qwen3.8-max" isn't described by this version's model catalog; update Claude Code, or map it with behavesAs on a modelPicker row (or modelOverrides, if it is a provider id of a model this version knows). Until then auto-compact keeps this session within 200k tokens...

This warning triggers because Claude Code relies on a hardcoded internal model catalog. When you pass an unrecognized model identifier, the CLI falls back to a conservative 200,000-token context window limit and triggers aggressive auto-compact routines to preserve context space.

You can remove this warning, prevent premature context truncation, and unlock the model’s full context capacity through environment variables or CLI configurations.

Method 1: Environment Variables (Fastest Fix)

Injecting environment variables directly into your shell session or shell profile bypasses local catalog checks without touching complex JSON files.

Disable Unknown Model Window Enforcement

Setting CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1 disables local context truncation entirely, delegating context limits and token management back to your backend API gateway.

# macOS / Linux / WSL (Zsh & Bash)
export CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1

# Windows PowerShell
$env:CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT="1"

Set Explicit Token Limits

If your backend provider supports a 1,000,000-token (1M) context window for qwen3.8-max, declare the exact token ceiling to overwrite the default 200k restriction:

# macOS / Linux / WSL (Zsh & Bash)
export CLAUDE_CODE_MAX_CONTEXT_TOKENS=1000000

# Windows PowerShell
$env:CLAUDE_CODE_MAX_CONTEXT_TOKENS="1000000"

Add these environment variables to your shell startup file (~/.zshrc or ~/.bashrc) and execute source ~/.zshrc so the configuration persists across all new terminal sessions.

Method 2: Temporary In-Line Model Flag ([1m])

For quick terminal sessions where you do not want to alter global configurations, leverage Claude Code’s internal model string parser by appending [1m] directly to the model name in your CLI invocation.

claude --model "qwen3.8-max[1m]"

The CLI’s regex parser detects the [1m] suffix, automatically sets the internal context capacity to 1,000,000 tokens, and suppresses the unknown model warning for that active session.

Method 3: Model Mapping in settings.json

To force Claude Code to handle custom model IDs as native models, configure mapping rules in the global configuration file using modelOverrides or modelPicker with behavesAs.

Locate your configuration file at the following path:

  • ☾ macOS / Linux / WSL: ~/.claude/settings.json
  • ☾ Windows (PowerShell): $HOME\.claude\settings.json (e.g., C:\Users\<Username>\.claude\settings.json)

Create or update the file with the following complete JSON configuration:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "env": {
    "CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT": "1",
    "CLAUDE_CODE_MAX_CONTEXT_TOKENS": "1000000"
  },
  "modelOverrides": {
    "claude-3-7-sonnet-20250219": "qwen3.8-max",
    "claude-3-5-haiku-20241022": "qwen3.8-max"
  },
  "modelPicker": [
    {
      "id": "qwen3.8-max",
      "label": "Qwen 3.8 Max (Custom Route)",
      "behavesAs": "claude-3-7-sonnet-20250219"
    }
  ],
  "autoApprove": [
    "Read",
    "Glob",
    "Grep"
  ],
  "theme": "dark"
}

Key Configuration Directives Explained

  • ☾ env Block: Defines environment variables directly inside the application config, ensuring settings load consistently across different terminal environments without altering system-level shell profiles.
  • ☾ modelOverrides Block: Maps native model keys (such as claude-3-7-sonnet-20250219) to target provider IDs (qwen3.8-max). The CLI processes tool calls and formatting rules as Sonnet locally, while swapping the model name in outgoing network payloads.
  • ☾ modelPicker Block: Registers custom options in the CLI model selection menu. The behavesAs attribute instructs the interface to inherit structural behaviors from a recognized catalog model.

Quick Reference & Configuration Matrix

Goal Method Syntax / Config Example
Quick Single-Session Fix Append model suffix claude --model "qwen3.8-max[1m]"
Suppress Warning Globally Shell Environment Variable export CLAUDE_CODE_DISABLE_UNKNOWN_MODEL_WINDOW_ENFORCEMENT=1
Set Custom Token Capacity Context Limit Variable export CLAUDE_CODE_MAX_CONTEXT_TOKENS=1000000
Map Custom API Endpoints Edit settings.json Set "claude-3-7-sonnet-20250219": "qwen3.8-max" in modelOverrides

Frequently Asked Questions (FAQ)

Q1: Why does Claude Code show a 200k token warning for custom models?

Claude Code checks requested model IDs against an internal catalog. When a model ID like qwen3.8-max is missing from that catalog, the application defaults to a conservative 200k-token window to prevent unexpected context overflow errors, triggering auto-compaction earlier than necessary.

Q2: Where should the behavesAs parameter be placed in the config?

The behavesAs property belongs inside the modelPicker array in ~/.claude/settings.json. It tells Claude Code to apply the prompting rules, tool-use structures, and context behaviors of a known model to your custom model entry.

Q3: What is the difference between modelOverrides and using --model?

Using modelOverrides allows the CLI to run its native internal logic (like token counting and prompt formatting) under a standard model profile while replacing the model string during outbound API calls. Passing an unknown string to --model without overrides triggers defensive fallback mode.

Q4: Does setting CLAUDE_CODE_MAX_CONTEXT_TOKENS=1000000 disable auto-compact?

Auto-compact remains active, but its invocation threshold shifts from the default 200k tokens up to 1M tokens, stopping premature history compression on long coding sessions.

Q5: Can I fix this error by updating the Claude Code CLI?

Running npm update -g @anthropic-ai/claude-code updates the catalog for newly released official Anthropic models. However, third-party, custom-routed, or self-hosted model IDs still require manual environment variable overrides or modelOverrides configuration.

Q6: How do I create settings.json if the .claude directory does not exist on Windows?

Create the .claude folder inside your user directory at C:\Users\<Username>\.claude, create a plain text file named settings.json, paste the JSON configuration inside, and launch PowerShell to verify.