Skip to main content

Bitbucket Integration Troubleshooting

Error Tracking​

When syncing entities from Bitbucket fails, the system tracks errors in the entity's git_integration field and displays them in the UI with a warning icon. Hovering over the icon shows the specific error details.

Error Types​

The following error codes may be displayed:

Error CodeHTTP CodeDescriptionResolution
INVALID_JSON400The JSON file contains invalid syntaxFix JSON syntax errors in the file
VALIDATION_FAILED400Required fields (name or slug) are missingAdd missing required fields to the entity
EMPTY_DIRECTORY400Skill directory is empty or missing SKILL.mdAdd SKILL.md file to the skill directory
MISSING_INTEGRATION400Referenced integration doesn't exist in your organizationAdd the integration or update the toolkit to use existing integrations
MISSING_TOOL400Referenced tool doesn't exist in the integrationCheck tool slugs match available tools in the integration
FETCH_FAILED500Failed to fetch the file from BitbucketCheck OAuth consumer permissions and repository access

Error Resolution​

Errors are automatically cleared when:

  • The same entity file is successfully synced from Bitbucket
  • You manually edit the entity in the admin panel (which triggers a new sync)

To view errors, look for the warning icon (⚠️) next to the entity name in the list view. Hover over it to see the error code and message.

Troubleshooting​

Connection Test Fails​

Error: "Connection test failed. Please verify your Workspace, Client ID, and Client Secret are correct."

  • Verify the workspace slug matches exactly (case-sensitive)
  • Ensure the OAuth consumer credentials (Key and Secret) are correct
  • Check that the OAuth consumer has the required repository permissions

Webhook Not Working​

Entities not syncing from Bitbucket to database

  1. Check webhook deliveries in your repository's webhook settings
  2. Look for failed webhook requests
  3. Verify the webhook URL is correct and accessible
  4. Check your application logs for webhook processing errors
  5. Ensure files are in the correct directories (toolkits/, commands/, skills/, etc.)

Webhook signature validation fails

  • Ensure the webhook secret matches exactly in both places
  • Don't include extra spaces or newlines in the secret

Sync Failures​

"Repository is empty" or "Branch not found"

  • The repository might not have a default branch yet
  • Create an initial commit (e.g., a README file) to initialize the repo
  • Ensure you're using the default branch name (usually main or master)

"Permission denied"

  • Verify the OAuth consumer has Repositories: Read and write permission
  • Re-create the consumer and update your admin settings if permissions were changed

Entity shows error indicator

  • Check for a warning icon (⚠️) next to the entity name in the list view
  • Hover over the icon to see the specific error message
  • See the Error Tracking section above for resolution steps
  • Fix the issue in Bitbucket or the admin panel, then push/save to clear the error

"Sync successfully 0 entities" or nothing syncing

If the sync completes without errors but 0 entities are synced to Bitbucket, check:

  1. Branch Protection Rules

    • Bitbucket branch restrictions may be blocking commits
    • Check your repository's branch restrictions settings
    • Ensure the OAuth consumer is permitted to push, or disable restrictions temporarily

  2. Network/Firewall Issues

    • Your server may be unable to reach Bitbucket's API
    • Check outbound network connectivity to api.bitbucket.org
    • Verify firewall rules allow HTTPS traffic to Bitbucket
    • Test with: curl -I https://api.bitbucket.org

  3. Repository State

    • Ensure the repository has an initialized default branch
    • Check that the branch name in your configuration matches the actual default branch

  4. Entity Eligibility

    • Only organization-level entities are synced to Bitbucket
    • Check if you have any organization-level entities in your database
    • User-specific or private entities are intentionally excluded from sync
    • MCP Clients do not have an owner_id field and are always synced

Security Best Practices​

  1. OAuth Consumer Credentials

    • Never commit the Client Secret to version control
    • Store it securely (encrypted environment variables or secrets manager)
    • Rotate credentials if they are ever exposed

  2. Webhook Secrets

    • Always use webhook secrets in production
    • Use a cryptographically secure random string
    • Rotate secrets if they're ever exposed

  3. Repository Permissions

    • Grant the OAuth consumer access only to the configuration repository
    • Review consumer permissions regularly

  4. Sensitive Data Handling

    • MCP Server auth credentials (API keys, secrets, OAuth) are automatically excluded from sync
    • Never manually add sensitive data to your Bitbucket repository
    • Use your database/admin panel for managing authentication settings

  5. Monitor Access

    • Regularly review OAuth consumer usage in your workspace settings
    • Check webhook delivery logs for suspicious activity
    • Audit configuration changes through Git history
On this page