Error Codes

When commands fail, the CLI returns structured errors with specific error codes. Understanding these codes helps you diagnose issues quickly.

Error Code Ranges

Range	Category	Description
1xxx	Authentication	Login, credentials, and token issues
2xxx	API	Bitbucket API request failures
3xxx	Git	Local git operations
4xxx	Configuration	Config file read/write issues
5xxx	Validation	Invalid input or missing required fields
6xxx	Context	Repository/workspace detection issues
7xxx	Network	Transport/network failures before API response
8xxx	Output formatting	`--json fields` and `--jq` evaluation issues
9xxx	Shell completion / Unknown	Completion install/uninstall failures and uncategorized errors

Authentication Errors (1xxx)

1001 - AUTH_REQUIRED

Message: Authentication required

Cause: You haven’t logged in yet, or your credentials have been cleared.

Solution:

bb auth login

1002 - AUTH_INVALID

Message: Invalid credentials

Cause: Your credentials were rejected by Bitbucket at request time. This is the code emitted for any 401 response that was not recovered by an OAuth refresh — e.g. a wrong API token, a revoked password, or basic-auth requests with bad credentials.

Solution:

Verify your Bitbucket username
Generate a new API token at Bitbucket API Tokens
Re-authenticate:

bb auth logout
bb auth login

1003 - AUTH_EXPIRED

Message: OAuth token expired. Run bb auth login to re-authenticate.

Cause: Specifically: an OAuth access token expired and the reactive refresh attempt also failed (refresh token revoked or expired). For non-OAuth flows, a stale token surfaces as AUTH_INVALID (1002) instead.

Solution:

Re-run bb auth login to perform a fresh OAuth flow
If that also fails, create a new API token in Bitbucket settings and switch auth methods

API Errors (2xxx)

2001 - API_REQUEST_FAILED

Message: API request failed

Cause: General network or API failure.

Solution:

Check your internet connection
Verify Bitbucket status at status.bitbucket.org
Retry the command

2002 - API_NOT_FOUND

Message: Resource not found

Cause: The requested repository, PR, or resource doesn’t exist.

Solution:

Check spelling of workspace and repository names
Verify the resource exists in Bitbucket
Ensure you have access to the repository

2003 - API_FORBIDDEN

Message: Access denied

Cause: Your API token doesn’t have the required permissions.

Solution:

Check your API token scopes at Bitbucket API Tokens
See Token Scopes for the exact scope each bb command requires.
If a scope is missing, mint a new token (you can’t add scopes to an existing one) and re-authenticate with bb auth login.

2004 - API_RATE_LIMITED

Message: Rate limit exceeded

Cause: You’ve made too many API requests in a short period.

Solution:

Wait a few minutes before retrying
For scripts, implement exponential backoff
Consider caching results when possible

2005 - API_SERVER_ERROR

Message: Bitbucket server error

Cause: Bitbucket’s servers are experiencing issues.

Solution:

Check status.bitbucket.org
Retry after a few minutes

Git Errors (3xxx)

3001 - GIT_NOT_REPOSITORY

Message: Not a git repository

Cause: The current directory is not a git repository, but the command requires one.

Solution:

Navigate to a git repository directory, or
Use explicit flags: -w <workspace> -r <repo>

3002 - GIT_COMMAND_FAILED

Message: Git command failed

Cause: A git operation (clone, fetch, checkout) failed.

Solution:

Ensure git is installed and in your PATH
Check git error message for details
Verify you have proper SSH keys or credentials configured

3003 - GIT_REMOTE_NOT_FOUND

Message: No Bitbucket remote found

Cause: The repository has no remote pointing to Bitbucket.

Solution:

Add a Bitbucket remote:

git remote add origin git@bitbucket.org:workspace/repo.git

Or use explicit flags: -w <workspace> -r <repo>

Config Errors (4xxx)

4001 - CONFIG_READ_FAILED

Message: Cannot read config file

Cause: The configuration file is corrupted or unreadable.

Solution:

Check file permissions
If corrupted, delete and recreate:

# macOS/Linux
rm ~/.config/bb/config.json
bb auth login

# Windows
del %APPDATA%\bb\config.json
bb auth login

4002 - CONFIG_WRITE_FAILED

Message: Cannot write config file

Cause: No write permission to the config directory.

Solution:

Check directory permissions
Ensure the parent directory exists
On shared systems, verify you own the config directory

4003 - CONFIG_INVALID_KEY

Message: Invalid configuration key

Cause: Attempted to get/set an unknown configuration key.

Solution: Valid configuration keys are:

defaultWorkspace - Default workspace
skipVersionCheck - Disable update notifications
versionCheckInterval - Days between update checks

bb config set defaultWorkspace myworkspace
bb config list

Validation Errors (5xxx)

5001 - VALIDATION_REQUIRED

Message: Required field missing

Cause: A required option or argument was not provided.

Solution: Check command help for required options:

bb <command> --help

Common required fields:

bb pr create requires --title
bb repo create requires a name argument

5002 - VALIDATION_INVALID

Message: Invalid value

Cause: A provided value doesn’t match expected format.

Solution:

Check the expected format in command help
Common issues:
- PR ID must be a number
- State must be one of: OPEN, MERGED, DECLINED, SUPERSEDED

5003 - FILE_NOT_FOUND

Message: File not found: <path>

Cause: A file referenced by an option (e.g. --file for bb snippet create/edit, --body-file for bb pr edit) doesn’t exist on disk, or a named file isn’t present inside a snippet.

Solution:

Verify the path is correct relative to the current working directory
For bb snippet view --file <name>, list snippet files first to confirm the name

The context field on this error includes the missing path under file (or bodyFile), which scripts can key on to differentiate it from a generic VALIDATION_INVALID.

Context Errors (6xxx)

6001 - CONTEXT_REPO_NOT_FOUND

Message: Could not determine repository

Cause: The CLI couldn’t figure out which repository to use.

Solution:

Use explicit flags:

bb pr list -w myworkspace -r myrepo

Set a default:

bb config set defaultWorkspace myworkspace

Run from within a cloned Bitbucket repository

See Understanding Repository Context for details.

6002 - CONTEXT_WORKSPACE_NOT_FOUND

Message: Could not determine workspace

Cause: The CLI couldn’t figure out which workspace to use.

Solution:

Use the -w flag:

bb repo list -w myworkspace

Set a default workspace:

bb config set defaultWorkspace myworkspace

Network Errors (7xxx)

7001 - NETWORK_ERROR

Message: Network error: Unable to reach Bitbucket API

Cause: The request failed before an HTTP response was received (offline, DNS issue, proxy/TLS issue, etc.).

Solution:

Check internet and DNS connectivity
Verify proxy/TLS settings if applicable
Retry the command after connectivity is restored

Output Formatting Errors (8xxx)

8001 - JQ_FAILED

Message: jq evaluation failed: <jq compiler error>

Cause: The expression passed to --jq is invalid or produced a runtime error.

Solution:

Test the expression interactively against the full output first:

bb pr list --json | jq '<expression>'

The embedded jq is jq 1.8.x; module imports (include, import) are not supported.
Remember --jq runs after field projection — when combined with --json fields, the input is already a flat array (the wrapper has been dropped).

8002 - JSON_FORMAT_INVALID

Message: --jq requires --json or similar formatting validation failure.

Cause: Incompatible combination of output flags.

Solution:

--jq requires --json. Add --json (with or without a field list).

Shell Completion Errors (9xxx)

9001 - COMPLETION_INSTALL_FAILED

Message: Failed to install completions: <reason>

Cause: bb completion install couldn’t write the shell completion hooks — typically because the target shell profile isn’t writable, or the underlying tabtab install failed.

Solution:

Check write permissions on your shell rc file (e.g. ~/.zshrc, ~/.bashrc)
Re-run with DEBUG=true bb completion install for the underlying error
If the issue persists, install completions manually by following your shell’s documentation for tabtab

9002 - COMPLETION_UNINSTALL_FAILED

Message: Failed to uninstall completions: <reason>

Cause: bb completion uninstall couldn’t remove the completion hooks — usually because the rc file isn’t writable or the entry was already removed manually.

Solution:

Check write permissions on your shell rc file
Manually remove the tabtab block from your shell rc file if needed

Unknown Errors (9xxx)

9999 - UNKNOWN

Message: An unexpected error occurred

Cause: The CLI encountered an error that doesn’t fit any known category.

Solution:

Check the error message for details
Retry the command
If the issue persists, report it with full debug output:

DEBUG=true bb <your-command> 2>&1

Exit Codes and Error Codes

The process exit code is intentionally minimal — 0 for success and 1 for any failure. The numeric error code on this page lives in the JSON error payload’s code field, not in the exit status. To branch on a specific failure mode in a script, parse stderr JSON and read .code.

See Exit Codes in the scripting guide for a full example.

Handling Errors in Scripts

When using the CLI in scripts, check the exit code and handle errors appropriately:

#!/bin/bash
set -e

if ! bb pr list -w myworkspace -r myrepo --json > prs.json 2>&1; then
  echo "Failed to list PRs"
  exit 1
fi

# Process prs.json...

For JSON output, errors are emitted to stderr and include the error code:

bb pr view 999 --json 2>&1
# {"name":"BBError","code":2002,"message":"Pull request not found"}

Typical JSON error payload fields:

name - Error class name
code - Numeric CLI error code
message - Human-readable message
context - Optional structured metadata