AegisGitea-MCP/docs/troubleshooting.md

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.
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: the name you used is not allowed. Add it to ALLOWED_HOSTS or set PUBLIC_BASE_URL.
• 429: the client exceeded RATE_LIMIT_PER_MINUTE.
• Responses arrive in one chunk or time out behind nginx: set proxy_buffering off;.

OAuth sign-in

• 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.