76 lines
3.4 KiB
Markdown
76 lines
3.4 KiB
Markdown
# 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:
|
|
```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
|