Repository navigation
Troubleshooting
Failures that really happen, in the shape symptom → cause → what to do.
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.
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.
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.
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.
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.
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.
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.