Skip to content

Troubleshooting

Vladimir Kochnev edited this page Nov 17, 2026 · 1 revision

Troubleshooting

Failures that really happen, in the shape symptom → cause → what to do.

The port is taken

Symptom. The set stays stopped, or start answers порт 9100 занят другим процессом / порт 9100 занят набором other. Cause. Ports 9100–9199 are shared with the test suites and other host services; the busy check listens on 0.0.0.0, so a listener on any host address counts. What to do. Let the allocator pick a port — an explicit port is refused, never moved. mcprig doctor lists foreign listeners in the range.

переменная X: источник не найден

Symptom. Start answers 409 with переменная VAR: источник не найден (OpenBao, env.json, окружение); набор S не запущен. Cause. A server references ${VAR} that no source has, and a set never starts on a half-empty environment — it would only fail later, in its own log. What to do. Define it in the environment, env.json or OpenBao. Only ${NAME} is a reference: ${NAME:-default} reaches the server as written.

tools.lock.json does not parse

Symptom. Every call is refused with 🚫 Карантин неизвестен: файл одобрений не прочитан (tools.lock.json не разобран: …) — вызов … отклонён. Cause. The file that records approved descriptors is corrupt, and the set will not read it as a blank slate — it refuses calls instead of approving silently. What to do. Repair or delete $MCPRIG_DATA_DIR/sets/<id>/tools.lock.json. A missing file is a normal start: the first descriptor seen is approved.

401 on /mcp

Symptom. The client connects but every request answers 401, or sees no tools. Cause. A closed set (allowAnonymous: false) wants a bearer key; an open set rejects any Authorization header it is given. Revoking the last active key stops the set and a restart answers у набора S нет активного ключа — выдайте новый. What to do. Use the key from mcprig init --client … --set <id>; issue a new key after a revocation; on an open set, remove the header.

403 on a panel write

Symptom. A button or a script fails with 403 "не хватает заголовка Origin". Cause. A cookie-authenticated write must carry Origin, compared in full — scheme, host and port; behind TLS the request looks like plain http. What to do. Send Origin; set X-Forwarded-Proto: https (and X-Forwarded-Host, X-Forwarded-Port) in the proxy; align MCPRIG_PUBLIC_URL.

A stdio server does not see a host variable

Symptom. The server starts but reports a missing key, while the same command works by hand. Cause. A stdio process does not inherit the host environment: it gets PATH, HOME, LANG, TZ, TMPDIR, NODE_EXTRA_CA_CERTS, LC_*, XDG_*, SSL_* and the proxy addresses (HTTP_PROXY, HTTPS_PROXY, NO_PROXY, NODE_USE_ENV_PROXY). What to do. Name the variable in the server's envAllow, or set it in env.

The answer came back cut

Symptom. The result ends with [обрезано: 32768 из 149873 байт, полный ответ — /…/tool-out/1f3c9a2b7d4e5f60.txt] or carries _truncated. Cause. maxBytes defaults to 32768; a larger answer is cut and the whole one is written to tool-out/. What to do. Read the file the marker names (it lives 24 hours), or pass a larger maxBytes, up to 1048576.

Details: docs/en/troubleshooting.md.

Clone this wiki locally