AegisGitea-MCP/docs/troubleshooting.md

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:

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