---
title: "Katman troubleshooting: common problems and fixes"
description: "Fixes for common Katman problems: server not showing up, wrong project folder, missing keys, locked tools, 402 errors, Cloudflare challenges, empty pages."
url: https://katman.pro/docs/troubleshooting
lang: en
updated: 2026-09-30
---

Docs Updated 30 Sep 2026

# Troubleshooting

> Most Katman problems come from five places: the MCP client can’t start the server, Katman is looking at the wrong folder, a key (KATMAN_KEY or the OpenRouter key) isn’t in the server’s environment, your plan doesn’t cover the tool (Audit Week has ended, or the tool needs Pro), or your site blocks the audit. Each section below starts with the symptom and gives the fix.

## Katman doesn’t appear in my editor

1.  **Check Node.js.** Katman needs version 20 or newer: `node --version`.
2.  **Check the package runs:** `npx -y katman-mcp --version` should print a version number.
3.  **Check your config file.** One trailing comma breaks JSON. Compare it with the snippets in [Getting started](https://katman.pro/docs/getting-started).
4.  **Restart the client completely.** Many clients only read MCP config at start-up; quit Claude Desktop from the menu bar, not just the window.
5.  **Give the first start more time.** The first `npx` download can be slow. In Codex CLI, set `startup_timeout_sec = 30`.
6.  **On Windows,** if the client can’t find `npx`, use `"command": "cmd"` with `"args": ["/c", "npx", "-y", "katman-mcp"]`.
7.  **Read the client’s MCP log.** When Katman starts, it writes `katman-mcp <version> ready (stdio)` to stderr.

## A tool says it needs Audit Week or Pro

**Symptoms:** instead of running, a tool such as `katman_audit_site`, `katman_plan` or `katman_visibility_run` explains how to get Audit Week or Pro. From a terminal, commands such as `npx -y katman-mcp audit`, `check` or `report` exit with code 4.

This is the upsell message, not an error. Run `katman_account`, which works without a key, to see why:

-   **No key found.** `KATMAN_KEY` isn’t in the server’s environment. If you haven’t yet, buy Audit Week or Pro; then create a key at [katman.pro/app](https://katman.pro/app/login) → **MCP**, put it in the client’s `env` block (not only in your terminal), and restart the server. The snippets per client are in [Getting started](https://katman.pro/docs/getting-started).
-   **Audit Week ended.** Audit Week lasts 7 days from payment and has no auto-renewal: buy Pro in **Billing** in your account to keep going. Each account can buy Audit Week once. The same key starts working again at the next plan check, and everything in `.katman/` is still there.
-   **Your Pro subscription has ended.** After you cancel, Pro keeps working until the end of the period you’ve paid for; if a renewal payment fails, it keeps working for up to 14 days while Stripe retries the card. After that, subscribe again in **Billing**; the same key starts working again at the next plan check.
-   **The key was revoked or isn’t valid.** Keys revoked in your account stop working at the next plan check. Create a new key and replace the old one in your config. A value that doesn’t look like a Katman key (`km_live_…`) is never sent.

## A tool says it needs Pro, but you have Audit Week

**Symptoms:** with an Audit Week key, `katman_prompt`, `katman_page_brief`, `katman_generate`, `katman_indexnow`, `katman_setup_monitoring` or `katman_sync` explains that it needs Pro instead of running. From a terminal, `npx -y katman-mcp indexnow` exits with code 4.

That’s how Audit Week works, not an error: it finds what’s wrong and tells you what to do; building pages and writing files is Pro. The ten audit and recommendation tools keep working until Audit Week ends. To use the Pro tools, buy Pro in **Billing** in your account; the same key unlocks them at the next plan check. Which tool needs which plan is on [Tools](https://katman.pro/docs/tools).

## Katman can’t reach katman.pro

Katman checks your key at most once a day and caches the answer in `~/.katman/license.json`. If katman.pro can’t be reached, the tools keep working for 7 days after the last successful check; after that, they show the upsell message until a check succeeds. Audit Week never runs past its end date, online or offline. Behind a corporate proxy, allow HTTPS to `katman.pro`.

## Katman is looking at the wrong folder

**Symptoms:** “Project root resolved to …, which is not a project folder”, or “No project files (package.json, index.html, framework config…) found in …”.

**Fix:** open your site’s project folder in your editor, or pass `project_root` with its absolute path, or set `KATMAN_PROJECT_ROOT` in the server’s `env` block. Claude Desktop has no project folder, so it always needs `KATMAN_PROJECT_ROOT`. Katman checks `project_root`, then `KATMAN_PROJECT_ROOT`, then the root your client reports, then the current folder.

## “No OpenRouter key” or the key is rejected

**Symptoms:** a visibility run stops with “no OpenRouter key”, or “key rejected (401)”.

-   The key must be in the environment of the MCP server, not only in your terminal. Editors started from the Dock or Start menu don’t read your shell profile.
-   Gemini CLI doesn’t pass variables with KEY or TOKEN in their names, so list the key under `env`.
-   Codex CLI’s `env_vars` forwards the key from the shell that started Codex.
-   A 401 means OpenRouter doesn’t accept the key: create a new one at [openrouter.ai/keys](https://openrouter.ai/keys). Nothing is spent when a key is rejected.

Restart the MCP server after any change.

## Error 402: out of credits

OpenRouter returns 402 when your credit or your key’s spending limit has run out. Katman stops the run, keeps the answers it already has, and marks the remaining questions “not run”, so a half-finished run never shows a false “not mentioned”.

**Fix:** add credit or raise the key’s limit at openrouter.ai, then run the dry run again to see the estimate and your remaining credit. To spend less, use `models: "probe"`, fewer `question_ids`, or a lower `max_cost_usd`; a run won’t start if its estimate is above the cap ($3 by default). A short-lived 402 about an “in-flight budget” is retried automatically. More on costs: [Visibility runs](https://katman.pro/docs/visibility-runs).

## The run says “research needed first”

A visibility run needs your question set, and the question set needs your brand name, domain and 10–12 customer situations. Call `katman_research` with `generate_questions: true`, then run the dry run again.

## A model returns 404, or a family is missing

A model can disappear from OpenRouter’s catalog. Katman skips that model’s remaining questions in the current run, and the next run picks the next live model in the same family. If no model of a family is available, the dry run says so before anything is spent.

## The audit shows AI bots getting 403 or a challenge

Your CDN or firewall is stopping them before they reach your site. A `cf-mitigated: challenge` response header means Cloudflare served a challenge page. Follow [Cloudflare is blocking AI crawlers](https://katman.pro/cloudflare-blocking-ai-crawlers), then run the audit again.

The audit tests bots by their user agent. Googlebot and Bingbot are verified by IP address, so check their real access in Search Console and Bing Webmaster Tools. If Cloudflare challenges the audit’s own requests, the page results are incomplete, but the bot-access table still shows which crawlers are blocked.

## My pages show 0 words, or very few, without JavaScript

Your site draws its text in the browser, and the audit reads the HTML the server sends, just like AI crawlers do. Ask your agent for `katman_prompt` with `id: "P2"`: it suggests the smallest change for your framework, such as prerendering the public pages.

**Lovable exception:** Lovable says older Lovable-hosted apps serve prerendered pages only to verified crawlers, so the audit may see the empty app while Google sees the text. Confirm with Search Console’s URL inspection live test. Apps created from 13 May 2026 are server-rendered ([Lovable docs](https://docs.lovable.dev/features/seo-aeo)).

## A missing page returns 200 (soft 404)

Single-page-app fallbacks send your index page for every unknown URL: `/* /index.html 200` in `_redirects`, a catch-all rewrite in `vercel.json`, or `not_found_handling: "single-page-application"` on Cloudflare Workers. Prompt P11 makes missing URLs return a real 404.

## The IndexNow key check fails

The key file must be served at `https://your-site.com/<key>.txt`, as plain text containing only the key. Deploy it before calling `katman_indexnow` with `dry_run: false`, and make sure a single-page-app fallback isn’t serving your index page at that address.

## Keyword research returns nothing

`katman_keywords` makes at most 40 throttled requests to Google’s autocomplete, which sometimes returns nothing for a while. Try again later, or try a shorter seed or another language.

## Results change between runs

That’s normal: assistants rarely give the same list twice. Compare how often you’re named across the whole question set, not your position in one answer, and use `samples` when you need to know how stable an answer is.

## Still stuck?

Email [hello@katman.pro](mailto:hello@katman.pro) with the output of `npx -y katman-mcp --version`, your editor and operating system, the tool you called and the full error text. Never include your OpenRouter key or an `.env` file. More on the [contact page](https://katman.pro/contact).

## Frequently asked questions

### How do I check that Katman runs at all?

Run npx -y katman-mcp --version in a terminal. If it prints a version, the package works and the problem is in your client’s configuration.

### Why does Katman say my project root is my home folder?

Because your client didn’t pass a project folder. Pass project\_root with the absolute path, or set KATMAN\_PROJECT\_ROOT in the server’s env block.

### I set OPENROUTER\_API\_KEY in my terminal. Why can’t Katman see it?

Because your editor starts the server with its own environment. Put the key in the server’s env block in the client config, then restart the server.

### A tool says I need Audit Week or Pro. What now?

Katman found no key with an active plan: KATMAN\_KEY isn’t in the server’s environment, your Audit Week or Pro subscription has ended, or the key was revoked. Run katman\_account, which needs no key, to see which; then add a key from katman.pro/app → MCP, or buy Pro in Billing.

### A tool says it needs Pro, but I have Audit Week. Why?

Audit Week covers the ten audit and recommendation tools: it finds what’s wrong and tells you what to do. Building pages and writing files is Pro, so katman\_prompt, katman\_page\_brief, katman\_generate, katman\_indexnow, katman\_setup\_monitoring and katman\_sync need Katman Pro.

### Does Katman stop working when katman.pro is down?

Not at once. Katman checks your key at most once a day, and the tools keep working for 7 days after the last successful check. Audit Week never runs past its end date.

### What does a 402 error mean?

OpenRouter says your credit or your key’s spending limit has run out. Add credit or raise the limit, then run the dry run again; answers not asked are marked “not run”, never “not mentioned”.

### Why does the audit show my pages with almost no words?

Because the text is drawn by JavaScript in the browser, and the audit reads the HTML the server sends, as AI crawlers do. Prompt P2 moves the text into the HTML.

### My answers change from run to run. Is Katman broken?

No. Assistants rarely give the same list twice, so compare how often you’re named across the whole question set, and use the samples option when you need a stability check.

## Related pages

-   [**Getting started with Katman** Install Katman MCP in Cursor, Claude Code, VS Code, Windsurf, Codex or Gemini CLI, add your Katman key and optional OpenRouter key, and run your first session.](https://katman.pro/docs/getting-started)
-   [**Tools reference** Reference for all 17 Katman MCP tools: what each one does, whether it needs Audit Week or Pro, its key inputs, what it writes, and an example call to copy.](https://katman.pro/docs/tools)
-   [**Visibility runs** How Katman measures AI visibility: 12+2 question set, five assistants via OpenRouter, cost caps, manual checks in the apps, and why one run is a small sample.](https://katman.pro/docs/visibility-runs)
-   [**Is Cloudflare blocking AI crawlers from my site?** robots.txt allows GPTBot but Cloudflare returns 403? The three AI bot types, the settings that block them, the 15 Sep 2026 change, a curl test and the fix.](https://katman.pro/cloudflare-blocking-ai-crawlers)
-   [**Contact** Email hello@katman.pro. What to include for site questions, Katman errors, account or billing questions, corrections and security reports, plus company details.](https://katman.pro/contact)

Updated 30 September 2026 · Katman