0 Fork 0

Files

T

Latte cf3d2e17d3 fix: fail closed on an unwritable audit log, bound the rate limiter and harden startup

The audit logger is opened at startup (exit 2 on failure) and obtained before
every call, which is refused with audit_unavailable otherwise. Audit records only
take validated path and sudo values and use the request id as correlation id. The
rate limiter evicts idle keys, caps tracked keys, audits the first excess per key
and window and uses the settings passed to the app. FORWARDED_ALLOW_IPS is now a
setting, and startup warns about a missing host allow-list and unavailable OAuth.

2026-10-14 16:24:51 +02:00

5.4 KiB

Raw Blame History

Troubleshooting

Start with the result of the failing call: errors carry error.status, error.kind and Gitea's sanitized message, and the audit log has one event per call (see audit-logging.md).

The server does not start

Message or exit	Cause and fix
Exit code 2, "GITEA_TOKEN" required (stdio)	stdio needs `GITEA_TOKEN`. Put it in the client's `env` block or in `.env` in the working directory the client starts the server in.
Exit code 2, refuses a non-loopback bind	`MCP_HOST` is not loopback and there is no `MCP_BEARER_TOKEN` or complete OAuth setup. Set one of them, or bind `127.0.0.1` behind a reverse proxy.
Exit code 2, lists OAuth settings	`OAUTH_ENABLED=true` needs `GITEA_OAUTH_CLIENT_ID`, `GITEA_OAUTH_CLIENT_SECRET`, `TOKEN_ENCRYPTION_KEY` and `PUBLIC_BASE_URL`.
Validation error naming a setting	See the rules in configuration.md: URLs must be http(s) without credentials, `PUBLIC_BASE_URL` must be https, secrets need 32 characters, `OAUTH_SCOPES` accepts only granular scopes.
Startup error listing tool names	`DISABLED_TOOLS` contains names that are not registered. Check tools.md.

stdio client shows nothing or breaks

stdout carries only JSON-RPC. If a wrapper script prints to stdout before the server starts, the client fails to parse the stream. Logs go to stderr; look at the client's MCP server log. uvx needs access to the package index that hosts aegis-gitea-mcp, see packaging.md.

Tool calls fail

`kind`	Meaning
`unauthorized` (401)	Gitea rejected the token: wrong, expired or revoked. In OAuth mode the user signs in again.
`forbidden` (403)	The token or the user lacks the scope or permission. Admin tools return this for non-admins. Widen the token scopes (see "Token scopes" in the README) or change the user's rights in Gitea. Sudo needs a site-admin token.
`not_found` (404)	The object does not exist, or Gitea hides it from this identity. Also returned for endpoints the Gitea version lacks.
`validation_failed` (422), `bad_request` (400)	Gitea rejected the values. The message says which.
`invalid_argument`	The arguments do not match the tool schema (missing, wrong type, extra property, bad owner or repository name). The message gives the path, not the value.
`timeout`, `upstream_unreachable`	Gitea did not answer within `REQUEST_TIMEOUT_SECONDS`, or the connection failed. Check `GITEA_URL` from the server's host (DNS, TLS, firewall).
`redirect`	Gitea answered with a redirect, which is never followed. Use the final URL (for example https) as `GITEA_URL`.
`payload_too_large`	The response is above `MAX_BINARY_BYTES`. Raise it or fetch a smaller object.
`secret_blocked`	`SECRET_DETECTION_MODE=block` withheld a result containing secret-like content. Use `mask` if that is acceptable.
`audit_unavailable`	The audit log could not be opened, so the call was refused before it reached Gitea. Fix the permissions of `AUDIT_LOG_PATH` (or `DATA_DIR`) and restart.
`rate_limited` (429)	Gitea or this server's `RATE_LIMIT_PER_MINUTE` limit.

A result with a truncated object was cut to MAX_TOOL_RESPONSE_ITEMS or MAX_TOOL_RESPONSE_CHARS. Use page and limit on paginated tools to walk through it.

A tool the client cannot see is probably filtered by TOOLSETS, READ_ONLY or DISABLED_TOOLS. Calling a filtered or unknown tool is a protocol error.

HTTP problems

GET /health returns 503 degraded: the server cannot reach Gitea (the probe is cached for 10 seconds). Fix connectivity from the server's host.
401 on /mcp: no or wrong bearer token, and no valid OAuth token. The response has a WWW-Authenticate header that points clients to the OAuth metadata.
Request rejected with an invalid Host (421): the name you used is not allowed. Add it to ALLOWED_HOSTS or set PUBLIC_BASE_URL. With a non-loopback MCP_HOST and neither variable the server prints a warning at startup that says so.
429: the client exceeded RATE_LIMIT_PER_MINUTE. If every client seems to share one limit, the proxy address is not in FORWARDED_ALLOW_IPS, so all requests look like they come from the proxy.
The server exits with code 2 and "cannot open the audit log": the audit file or its directory is not writable. Fix the permissions, or point AUDIT_LOG_PATH or DATA_DIR at a writable location (in Docker, check the volume ownership). The server never runs without an audit log.
Responses arrive in one chunk or time out behind nginx: set proxy_buffering off;.

The client reports that dynamic client registration is unsupported: OAuth is off. Set OAUTH_ENABLED=true and the settings that go with it.
Gitea shows a redirect URI error: the OAuth application's redirect URI must be exactly <PUBLIC_BASE_URL>/oauth/callback. Re-run setup --public-base-url ... or fix it in Gitea.
Signed in, but admin tools return 403: the user is not a site administrator. That is intended.
Users are asked to sign in again after a restart: TOKEN_ENCRYPTION_KEY or the DATA_DIR volume changed. The key must stay stable and the volume persistent.
After fixing OAuth settings the client still fails: some clients cache tokens. Disconnect the server in the client and connect again, which starts a fresh flow. Users can also revoke the application under Settings, Applications, Authorized OAuth2 Applications in Gitea.

5.4 KiB Raw Blame History