68 lines
4.7 KiB
Markdown
68 lines
4.7 KiB
Markdown
# 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](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](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](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](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](../README.md)) 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.
|