AegisGitea-MCP/docs/troubleshooting.md

Troubleshooting

"Internal server error (-32603)" from ChatGPT

Symptom: ChatGPT shows Internal server error with JSON-RPC error code -32603 when trying to use Gitea tools.

Cause: The OAuth token stored by ChatGPT was issued without Gitea API scopes (e.g. read:repository). This happens when the initial authorization request didn't include the correct scope parameter. The token passes OIDC validation (openid/profile/email) but gets 403 Forbidden from Gitea's REST API.

Fix:

1. In Gitea: Go to Settings > Applications > Authorized OAuth2 Applications and revoke the MCP application.
2. In ChatGPT: Go to Settings > Connected apps and disconnect the Gitea integration.
3. Re-authorize: Use the ChatGPT integration again. It will trigger a fresh OAuth flow with the correct scopes (read: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: Same root cause as above — the OAuth token doesn't have the required Gitea API scopes. The middleware's API scope probe detected this and returned a clear error instead of letting it fail deep in the tool handler.

Fix: Same as above — revoke and re-authorize.

ChatGPT caches stale tokens

Symptom: After fixing the OAuth configuration, ChatGPT still sends the old token.

Cause: ChatGPT caches access tokens and doesn't automatically re-authenticate when the server configuration changes.

Fix:

1. In ChatGPT: Settings > Connected apps > disconnect the integration.
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 will validate via the userinfo endpoint but will be rejected by Gitea's REST API with 403.

The MCP server's openapi-gpt.yaml file controls which scopes ChatGPT 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