Troubleshooting

This guide covers the most common issues users encounter and how to resolve them.

Authentication Issues

”Authentication required” Error

Symptoms:

Error: Authentication required. Please run 'bb auth login' first.

Causes:

You haven’t logged in yet
Your credentials were cleared

Solution:

bb auth login

“Invalid credentials” Error

Symptoms:

Error: Invalid credentials

Causes:

Incorrect username
Invalid or expired API token
Using a password instead of API token

Solution:

Verify your username is correct (your Bitbucket username, not email)
Generate a fresh API token:
- Go to Bitbucket API Tokens
- Create a new token with required scopes
- Copy the token immediately
Re-authenticate:
Terminal window
```
bb auth logout
bb auth login
```

Token Works in Browser but Not CLI

Causes:

Token might have wrong scopes
Token might be an app password (deprecated)
Encoding issues when pasting

Solution:

Verify you’re using an API token (not app password):
- API tokens are managed at API Tokens page
- App passwords are at a different URL (deprecated)
Check token scopes include:
- account:read
- repository:read and repository:write
- pullrequest:read and pullrequest:write

When pasting the token, ensure no extra whitespace:

# Good - token only
bb auth login -u myuser -p ATBB_xxxxx

# Bad - extra space
bb auth login -u myuser -p " ATBB_xxxxx"

Repository Context Issues

”Could not determine repository” Error

Symptoms:

Error: Could not determine repository. Use -w and -r flags or run from within a repository.

Causes:

Not in a git repository
Git remote doesn’t point to Bitbucket
No default workspace/repo configured

Solutions:

Option 1: Use explicit flags

bb pr list -w myworkspace -r myrepo

Option 2: Set defaults

bb config set workspace myworkspace
bb config set repo myrepo

Option 3: Work from a cloned repository

cd /path/to/cloned-bitbucket-repo
bb pr list  # Auto-detects from git remote

See Repository Context for details.

”Repository not found” Error

Symptoms:

Error: Repository not found

Causes:

Typo in workspace or repository name
You don’t have access to the repository
Repository was deleted or renamed

Solution:

Verify spelling:

# Check what the CLI detected
bb repo view

List repositories you have access to:
Terminal window
```
bb repo list -w myworkspace
```
Check Bitbucket web UI to confirm repository exists

Network Issues

”API request failed” Error

Symptoms:

Error: API request failed

Causes:

No internet connection
Bitbucket is down
Firewall blocking requests
Proxy not configured

Solutions:

Check internet connection:
Terminal window
```
curl -I https://api.bitbucket.org
```
Check Bitbucket status: status.bitbucket.org

If behind a proxy, configure it:

export HTTPS_PROXY=http://proxy.example.com:8080

Rate Limiting

Symptoms:

Error: Rate limit exceeded

Causes:

Too many API requests in a short period
Scripts making rapid sequential calls

Solutions:

Wait a few minutes and retry

For scripts, implement delays:

for pr_id in 1 2 3 4 5; do
  bb pr view $pr_id
  sleep 1  # Add delay between requests
done

Use --json and process locally to reduce API calls:

# One API call, process locally
bb pr list --json | jq '.[] | select(.author.username == "me")'

Git Integration Issues

”Not a git repository” Error

Symptoms:

Error: Not a git repository

Causes:

Running command outside a git repository
Git not initialized

Solutions:

Navigate to a git repository:
Terminal window
```
cd /path/to/your/repo
```
Or use explicit flags:
Terminal window
```
bb pr list -w workspace -r repo
```

Clone Fails

Symptoms:

Error: Failed to clone repository

Causes:

SSH keys not configured
Repository access denied
Invalid repository URL

Solutions:

Try HTTPS instead of SSH:

# The CLI uses SSH by default
# Clone manually with HTTPS if SSH fails
git clone https://bitbucket.org/workspace/repo.git

Check SSH configuration:
Terminal window
```
ssh -T git@bitbucket.org
```
Verify repository access in Bitbucket web UI

Command-Specific Issues

PR Creation Fails

Symptoms:

Error: Failed to create pull request

Common causes and solutions:

Cause	Solution
Branch doesn’t exist on remote	`git push -u origin your-branch`
PR already exists for branch	Check `bb pr list`
Branch protection rules	Check repository settings
No changes between branches	Ensure commits exist

PR Merge Fails

Symptoms:

Error: Cannot merge pull request

Common causes:

Merge conflicts exist
Required approvals not met
Build checks failing
Branch protection rules

Solution: Check PR status in Bitbucket web UI for specific blockers.

Diff Shows Nothing

Symptoms:

bb pr diff 42
# (empty output)

Causes:

PR has no file changes
PR is already merged
API returned empty diff

Solutions:

Check PR status:
Terminal window
```
bb pr view 42
```
View in browser:
Terminal window
```
bb pr diff 42 --web
```

Getting Debug Information

When reporting issues, gather this information:

# CLI version
bb --version

# OS information
uname -a  # Linux/macOS
systeminfo | findstr /B /C:"OS"  # Windows

# Node.js version
node --version

# Auth status (masks token)
bb auth status

# Config (masks token)
bb config list

Still Need Help?

If you’ve tried the solutions above and still have issues:

Search existing issues
Open a new issue with:
- CLI version (bb --version)
- Operating system
- Complete error message
- Steps to reproduce