Latte
b275f5c0c2
test / test (push) Has been cancelled
lint / lint (push) Has been cancelled
docker / test (pull_request) Successful in 13s
docker / lint (pull_request) Successful in 2m3s
lint / lint (pull_request) Successful in 16s
test / test (pull_request) Successful in 14s
docker / docker-test (pull_request) Successful in 42s
docker / docker-publish (pull_request) Has been skipped
77 lines
3.7 KiB
Markdown
77 lines
3.7 KiB
Markdown
# Troubleshooting
|
|
|
|
## "Internal server error (-32603)" from Claude
|
|
|
|
**Symptom:** Claude shows `Internal server error` with JSON-RPC error code `-32603` when trying to use Gitea tools.
|
|
|
|
**Cause:** In user-token mode, the OAuth token stored by the client may have been issued without Gitea API scopes (e.g. `read:repository`). In service-PAT mode, the call may fail because the authenticated user does not have the required repository permission or the permission probe cannot be completed.
|
|
|
|
**Fix:**
|
|
1. In Gitea: Go to **Settings > Applications > Authorized OAuth2 Applications** and revoke the MCP application.
|
|
2. In Claude: disconnect the MCP server and authenticate again.
|
|
3. Re-authorize: Use the MCP connector again. It will trigger a fresh OAuth flow. For repository-targeted calls in service-PAT mode, also verify the signed-in Gitea user has read/write access to the target repository.
|
|
|
|
**Verification:** Check the server logs for `oauth_auth_summary`. A working token shows:
|
|
```
|
|
oauth_auth_summary: api_probe=pass login=alice
|
|
```
|
|
A scopeless token shows:
|
|
```
|
|
oauth_token_lacks_api_scope: status=403 login=alice
|
|
```
|
|
|
|
## "Gitea rejected the API call" (403)
|
|
|
|
**Symptom:** Tool calls return 403 with a message about re-authorizing.
|
|
|
|
**Cause:** The OAuth token does not have the required API scope in user-token mode, or the per-user repository permission check denied the request in service-PAT mode.
|
|
|
|
**Fix:** Revoke and re-authorize if the token lacks API scope. If the error mentions repository permission, grant the signed-in Gitea user the required repository access or use a repository they can access.
|
|
|
|
## Claude caches stale tokens
|
|
|
|
**Symptom:** After fixing the OAuth configuration, Claude still sends the old token.
|
|
|
|
**Cause:** The client caches access tokens and doesn't automatically re-authenticate when the server configuration changes.
|
|
|
|
**Fix:**
|
|
1. Disconnect the server in the client.
|
|
2. Start a new conversation and use the integration again - this forces a fresh OAuth flow.
|
|
|
|
## How OAuth scopes work with Gitea
|
|
|
|
Gitea's OAuth2/OIDC implementation uses **granular scopes** for API access:
|
|
|
|
| Scope | Access |
|
|
|-------|--------|
|
|
| `read:repository` | Read repositories, issues, PRs, files |
|
|
| `write:repository` | Create/edit issues, PRs, comments, files |
|
|
| `openid` | OIDC identity (login, email) |
|
|
|
|
When an OAuth application requests authorization, the `scope` parameter in the authorize URL determines what permissions the resulting token has. If only OIDC scopes are requested (e.g. `openid profile email`), the token can establish identity but may not be usable for direct Gitea REST calls. When `GITEA_TOKEN` is configured, the server uses OIDC for identity and checks the user's repository permission before using the service PAT.
|
|
|
|
The MCP server's OAuth metadata controls which scopes the client requests. Ensure it includes:
|
|
```yaml
|
|
scopes:
|
|
read:repository: "Read access to Gitea repositories"
|
|
write:repository: "Write access to Gitea repositories"
|
|
```
|
|
|
|
## Reading the `oauth_auth_summary` log
|
|
|
|
Every authenticated request emits a structured log line:
|
|
|
|
| Field | Description |
|
|
|-------|-------------|
|
|
| `token_type` | `jwt` or `opaque` |
|
|
| `scopes_observed` | Scopes extracted from the token/userinfo |
|
|
| `scopes_effective` | Final scopes after implicit grants |
|
|
| `api_probe` | `pass`, `fail:403`, `fail:401`, `skip:cached`, `skip:error` |
|
|
| `login` | Gitea username |
|
|
|
|
- `api_probe=pass` — token works for Gitea API calls
|
|
- `api_probe=fail:403` — token lacks API scopes, request rejected with re-auth guidance
|
|
- `api_probe=skip:cached` — previous probe passed, cached result used
|
|
- `api_probe=skip:error` — network error during probe, request allowed to proceed
|
|
- `repository_permission_denied` in the audit log — the user lacks required read/write permission for a service-PAT call
|