Common failures

Read the message, fix the named file, key, or mode, then run the same command again. This is not a separate Debug product.

No model Provider

**What you see:** the first screen says **No model Provider is configured**. The main action is **Configure a model Provider** (c; l still works as an alias). There is no composer until a Provider is set. There is no browser OAuth, device code, or grok.com sign-in.

**What it means:** Matcha CLI has no BYOK credentials for inference. xAI is optional; it is not configured by default. MatchaCode is not a model vendor.

**What to do:**

matcha login --provider xai
matcha login --provider openai --from-env
printf 'KEY' | matcha login --provider anthropic

Provider ids: xai, openai, anthropic, openai_compatible (alias openai-compatible), ollama. The key is never accepted on the command line.

Typed /login in the TUI does **not** open a wizard. It prints the same CLI examples and says account login is unavailable.

You can also set the Provider’s official environment variable (XAI_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, …) or add a [model_providers.<id>] entry in ~/.matcha/config.toml.

Headless / ACP text uses the longer form: run matcha login --provider xai (or another id), set the official env var, or add the config entry.

Bad API key

**What you see:** the turn fails with an authentication error. The toast strips the Authentication failed: prefix, so you may only see the Provider’s message (for example **Incorrect API key provided**).

**What it means:** a key is stored or exported, but the Provider rejected it. This is not “no Provider.”

**What to do:**

1. matcha logout — clears the local vault entry. It does not revoke the key at the Provider.
2. matcha login --provider <id> again. Use the secure prompt, --from-env, or a pipe.
3. Optional: matcha login --provider <id> --validate to probe before store. A failed probe **does not overwrite** an existing valid key.

--oauth and --device-auth failing is expected. Use --provider.

Capability denied

**What you see:** a one-line refusal, often **… is unavailable in this Matcha build (Mode A).** Examples:

• /feedback — Feedback submission is unavailable…
• /usage manage — Account billing is unavailable…
• /release-notes — Remote release notes are not published… Use /docs…
• matcha update — Self-update is unavailable…
• /share, /marketplace, /login (account path) — same pattern

**What it means:** that surface is turned off. The binary still has the name so the error is clear. Retrying, setting MATCHA_TELEMETRY_*, or pointing config at a leftover product URL does not turn the feature on.

**What to do:** use the local substitute.

Fullscreen-only command in minimal

**What you see:**

/theme isn't available in minimal mode (minimal renders with your
terminal's own palette). Run /fullscreen to switch this session.

Other fullscreen-only names use the same shape with a different reason:

**What it means:** you are in --minimal / /minimal. --no-alt-screen is still the fullscreen TUI (inline), not minimal. Those commands work there.

**What to do:**

/fullscreen

Alias: /full. The session relaunches in the full TUI. Then run the command again.

The reverse (/minimal while already in the full TUI) relaunches in minimal. Commands that exist only in minimal (/expand, /edit-prompt) refuse in fullscreen with **Run /minimal to switch this session.**

Invalid config

**What you see:** Matcha CLI still starts, but something is ignored. Or a settings write says it is **refusing to overwrite unparseable** config.toml (TOML parse error; the message does not include secret lines).

**What it means:** one file or one table failed to parse. The loader skips the bad entry when it can, so a single typo does not wipe the rest of the config. Invalid MCP server rows do not prevent startup; they show up on inspect.

**What to do:**

matcha inspect
matcha inspect --json

Look at:

• **Config Sources** — (parse error) vs (empty) vs a live path
• **Config Warnings** — unknown fields, invalid values, conflicting keys
• **MCP Config Problems** — [error] / [warning] on a server entry
• **Config schema** — a future schema_version still loads known fields; alias conflicts name the keys, not the values

matcha doctor also prints config-schema, config-conflict, and env-conflict (canonical MATCHA_* overriding a registered GROK_* alias; **values are not shown**).

Fix the named file (usually ~/.matcha/config.toml or a project .matcha/ / .grok/ config). Save a valid TOML file, then inspect again. If a live session already loaded a previous file, restart matcha so the new parse is the one in memory.

If you are still stuck

1. /doctor or matcha doctor for the terminal.
2. matcha inspect for discovered project config.
3. /docs for the How-to Guides.
4. Confirm a Provider with matcha login --provider <id> if inference never starts.

Stay with the error you already have: fix the test, the named config line, or the Provider key. Do not treat /feedback or /announcements as the next step — those are not user recovery procedures in this Matcha CLI.