> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blitzy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Diagnose and resolve common integration issues across GitHub, Azure DevOps, GitLab, and Bitbucket

Resolve common issues when connecting or using your Blitzy integrations.

<Note>
  **Jump to:** [GitHub](#github-issues) | [Azure DevOps](#azure-devops-issues) | [GitLab](#gitlab-troubleshooting) | [Bitbucket](#bitbucket-issues) | [Getting Help](#getting-help)
</Note>

## GitHub Issues

* **Repository not appearing** - Ensure you've granted access through **GitHub Settings > Applications > Blitzy**
* **Permission denied errors** - Verify the Blitzy app has the required permissions
* **Organization access** - Organization owners may need to approve the app

## Azure DevOps Issues

* **Project not visible** - Confirm you have access to the project and have granted Blitzy access
* **Authentication errors** - Try disconnecting and reconnecting the integration
* **Service connection issues** - Check Azure DevOps project settings for service connection requirements

## GitLab Troubleshooting

<div id="gitlab-troubleshooting" />

For detailed information about GitLab's API and authentication, see [GitLab REST API Documentation](https://docs.gitlab.com/api/rest/).

<Note>
  **Quick Diagnosis:** Jump directly to your issue:

  * OAuth errors (authorization, state, tokens) - [OAuth & Authentication](#oauth-authentication)
  * Permission/scope errors - [Permission & Access](#permission-access)
  * Rate limiting - [Rate Limits](#rate-limits)
</Note>

### OAuth & Authentication

<div id="oauth-authentication" />

<AccordionGroup>
  <Accordion title="&#x22;access_denied&#x22; - OAuth Authorization Denied">
    **Error message:**

    ```json theme={null}
    {
      "error": "access_denied",
      "error_description": "The resource owner or authorization server denied the request"
    }
    ```

    The user clicked "Deny" or cancelled the OAuth authorization flow in GitLab.

    **Reference:** [GitLab OAuth 2.0 API](https://docs.gitlab.com/api/oauth2/)
  </Accordion>

  <Accordion title="&#x22;Invalid state parameter&#x22;">
    **Error message:**

    ```
    Could not authenticate you from OpenIDConnect because 'Invalid 'state' parameter'
    ```

    The OAuth state parameter verification failed. This is a security measure to prevent CSRF attacks. Common causes include expired state (>10 minutes), browser back button usage, or session/cookie issues.

    **Reference:** [GitLab OAuth 2.0 API](https://docs.gitlab.com/api/oauth2/)
  </Accordion>

  <Accordion title="&#x22;Token is expired&#x22;">
    **Error message:**

    ```json theme={null}
    {
      "error": "invalid_token",
      "error_description": "Token is expired. You can either do re-authorization or token refresh."
    }
    ```

    The access token has expired. From GitLab 16.0, all access tokens have an expiration date.

    **Reference:** [GitLab Token Troubleshooting](https://docs.gitlab.com/security/tokens/token_troubleshooting/)
  </Accordion>
</AccordionGroup>

### Permission & Access

<div id="permission-access" />

<AccordionGroup>
  <Accordion title="403 - &#x22;insufficient_scope&#x22;">
    **Error message:**

    ```
    The request requires higher privileges than provided by the access token
    ```

    The OAuth access token doesn't have the required scope for the requested operation.

    **Required scopes for integrations:**

    * `api` - Full API access
    * `read_api` - Read access to groups and projects
    * `write_repository` - Create branches and commits
    * `read_user` - User information access

    **Reference:** [GitLab REST API Authentication](https://docs.gitlab.com/api/rest/authentication/)
  </Accordion>
</AccordionGroup>

### Rate Limits

<div id="rate-limits" />

<AccordionGroup>
  <Accordion title="429 - &#x22;Retry later&#x22;">
    **Error message:**

    ```
    Retry later
    ```

    (Plain text response with 429 status code)

    You've exceeded GitLab's rate limits. GitLab.com limits are:

    * **Unauthenticated requests** - 500 requests/minute per IP
    * **Authenticated requests** - 2000 requests/minute per user

    The response includes a `Retry-After` header indicating when to retry.

    **References:**

    * [GitLab Rate Limits](https://docs.gitlab.com/security/rate_limits/)
    * [User and IP Rate Limits](https://docs.gitlab.com/administration/settings/user_and_ip_rate_limits/)
  </Accordion>
</AccordionGroup>

## Bitbucket Issues

<div id="bitbucket-issues" />

* **Repository not appearing** - Ensure you granted Blitzy the Repositories: Read permission during authorization
* **Permission denied errors** - Disconnect and reconnect the integration to re-authorize with the required scopes
* **Workspace access** - Verify you have access to the Bitbucket workspace containing the target repositories

## Getting Help

For issues not covered above, consult the official GitLab documentation:

* [REST API Troubleshooting](https://docs.gitlab.com/api/rest/troubleshooting/)
* [REST API Authentication](https://docs.gitlab.com/api/rest/authentication/)
* [OAuth 2.0 API](https://docs.gitlab.com/api/oauth2/)
* [Token Troubleshooting](https://docs.gitlab.com/security/tokens/token_troubleshooting/)
* [Rate Limits](https://docs.gitlab.com/security/rate_limits/)

For Blitzy-specific integration issues, email **[support@blitzy.com](mailto:support@blitzy.com)** with:

* Exact GitLab error message and status code
* Screenshot of the error
* GitLab Cloud or Self-Managed (with version if Self-Managed)
* Your GitLab role in the namespace
* When the error occurs (during setup, runtime, etc.)