Troubleshooting

Start with bb doctor. It checks Bun, the config file, network access, authentication, token scopes, and git remote detection, and points at the failing piece. Then find your error message below. Command errors go to stderr and exit 1, with a ✗ prefix, or ERR under --no-unicode or BB_NO_UNICODE. Under --json, command failures, argument-parser errors included, become a single-line JSON object on stderr. Interrupting an interactive prompt with Ctrl+C exits 130. BB_DETAILED_EXIT_CODES=1 gives each failure class its own exit status.

Installation

`bb` fails because `bun` is not found

The npm package runs on Bun, and npm install -g or pnpm add -g does not install it. Without Bun, bb stops before it starts. The exact error depends on the system:

macOS: env: bun: No such file or directory
Linux: /usr/bin/env: 'bun': No such file or directory
pnpm on macOS or Linux: exec: bun: not found
Windows: 'bun' is not recognized as an internal or external command

Install Bun 1.1.30 or newer (see Installation), open a new shell, and check bun --version. Or switch to the standalone binary, which needs no runtime.

Authentication

Authentication required

✗ Authentication required. Run 'bb auth login'.

No credentials are stored, you have not logged in, or bb auth logout cleared them.

bb auth login

OAuth token expired

✗ OAuth token expired. Run 'bb auth login' to re-authenticate.

The refresh token was revoked or expired, or the OAuth consumer was deleted.

bb auth logout
bb auth login

Invalid username or token

bb auth login reports a rejected API token like this:

✗ Invalid email or token: Unauthorized. Verify your Atlassian account email and that the API token is current and has the required scopes.

On any other command a 401 shows Bitbucket’s own message plus a dimmed remediation line:

✗ Unauthorized
Your Bitbucket credentials were rejected. Run `bb auth login` to re-authenticate.

If you authenticated with OAuth, re-authenticate:

bb auth logout
bb auth login

If you use an API token, first check that -u or BB_USERNAME is your Atlassian account email, not your Bitbucket username. If the token is expired or lacks scopes, mint a fresh one at Bitbucket API Tokens. Scopes cannot be added to an existing token. Log in again, keeping the token out of shell history:

printf '%s' "$BB_API_TOKEN" | bb auth login -u [email protected] --with-token

`bb auth login` never opens a browser

The most common cause is environmental, not network:

BB_API_TOKEN is exported in your shell. Its mere presence, even set to an empty string, selects API-token auth and skips OAuth entirely. Run unset BB_API_TOKEN and retry. (-u, -p, --app-password, and --with-token select the same path, deliberately.)
SSH session, headless machine, or WSL without browser integration.
No default browser configured.

bb prints the authorization URL to stderr. Open it in a browser that can reach localhost:19872 on the machine running the CLI. A browser on another host needs a loopback port-forward; otherwise use an API token:

printf '%s' "$BB_API_TOKEN" | bb auth login -u [email protected] --with-token

Port 19872 is already in use

✗ Port 19872 is already in use. Close the application using it and try again.

The OAuth callback server binds 127.0.0.1:19872 and waits up to 5 minutes.

lsof -i :19872   # macOS/Linux

Close the other bb auth login (or whatever holds the port) and retry. There is no fallback port: Bitbucket only accepts a redirect_uri that matches the OAuth consumer’s registered callback URL, which pins port 19872. If you can’t free the port, use an API token instead.

Token works in the browser but not in the CLI

Use your Atlassian account email with -u or BB_USERNAME.
Confirm it is an API token, minted at Bitbucket API Tokens. App passwords live at a different URL and no longer work.
Check the scopes cover what you are running. See Token Scopes. A missing scope surfaces as a 403 with the hint Your token may be missing a required scope.

Strip whitespace when pasting:

# Good - token only
bb auth login -u [email protected] -p ATBB_xxxxx

# Bad - leading space inside the quotes
bb auth login -u [email protected] -p " ATBB_xxxxx"

Config file has insecure permissions

✗ Config file has insecure permissions (644); expected 600. Run: chmod 600 /home/me/.config/bb/config.json

On macOS and Linux, bb refuses to read a config file or directory that is readable by group or other. This usually follows copying a config between machines or restoring a dotfiles repository. Windows skips the check.

chmod 700 ~/.config/bb
chmod 600 ~/.config/bb/config.json

A hand-edited file that no longer parses gives:

✗ Config file is not valid JSON: /home/me/.config/bb/config.json. Fix the file by hand or remove it and run `bb auth login` again.

Both are error code 4001 (CONFIG_READ_FAILED).

Repository context

Could not determine repository

✗ Could not determine repository. Use --workspace and --repo options, or run this command from within a Bitbucket repository.

Sibling messages name the specific reason:

✗ Not in a git repository. Use --workspace and --repo options, or run this command from within a Bitbucket repository.
✗ Git repository has no remote configured. Add a Bitbucket remote with `git remote add origin <url>`, or use --workspace and --repo options, or run this command from within a Bitbucket repository.
✗ Remote '[email protected]:me/thing.git' is not a Bitbucket URL. Use --workspace and --repo options, or run this command from within a Bitbucket repository.
✗ None of the git remotes (origin, gitlab) is a Bitbucket URL. Use --workspace and --repo options, or run this command from within a Bitbucket repository.
✗ Git remotes fork, mirror point to different Bitbucket repositories and neither origin nor upstream is one of them. Use --workspace and --repo options to pick one.

All are code 6001 (CONTEXT_REPO_NOT_FOUND). Pick whichever fix suits:

bb pr list -w myworkspace -r myrepo     # explicit flags
cd /path/to/cloned-bitbucket-repo && bb pr list

See Repository Context for the full precedence rules.

Repository or resource not found

Commands that know what they were looking for name it, and stop there:

✗ Repository my-ws/typo not found.
✗ Pull request #999 not found in my-ws/my-repo.

Everywhere else a 404 surfaces Bitbucket’s own message with a dimmed remediation line appended. See Failures that tell you the next step. In --json mode that line arrives as a top-level hint string on the error envelope.

Usual causes: a typo in the workspace or repository slug, a repository you have no access to, or one that was renamed. To check what you can actually see:

bb workspace list
bb repo list -w myworkspace

Network

Cannot reach Bitbucket

✗ Network error: Unable to reach Bitbucket API. Run with BB_DEBUG=http for details. If you're behind a proxy or using a custom CA, check your environment.

curl -I https://api.bitbucket.org          # connectivity
export HTTPS_PROXY=http://proxy.example.com:8080
BB_DEBUG=http bb repo list                 # [HTTP] tracing on stderr, secrets redacted

HTTP traces go to stderr, so --json output on stdout stays parseable while tracing is on. Verbose tracing redacts credentials but may include sensitive repository content; review it before sharing.

Bitbucket’s own availability is at status.bitbucket.org.

Request timed out

✗ Network error: Request to Bitbucket API timed out after 30000ms. The server accepted the connection but did not respond in time. Increase or disable the timeout via BB_HTTP_TIMEOUT (milliseconds; set BB_HTTP_TIMEOUT=0 to disable), or run with BB_DEBUG=http for details.

The per-request timeout defaults to 30000 ms.

BB_HTTP_TIMEOUT=60000 bb pr list   # 60 seconds
BB_HTTP_TIMEOUT=0 bb pr list       # no timeout

Rate limiting

A 429 is retried automatically. In human mode you see the attempts on stderr:

⚠ Rate limited, retrying in 1.0s (attempt 1/3)...

Retries cover HTTP 429, 502, 503, and 504, up to 3 retries (4 requests total). On a 429 the Retry-After header sets the delay when Bitbucket sends one; otherwise the delay is exponential backoff from 1s. Transient network failures on GET, HEAD, and OPTIONS share the same 3-retry budget. Once it is exhausted, the command fails with Bitbucket’s own 429 message.

The retry warning is suppressed in --json mode, so scripts see only the final failure.

If the limit is sustained:

Wait a few minutes and retry.

Add a delay between calls in loops:

for pr_id in 1 2 3 4 5; do
  bb pr view $pr_id
  sleep 1
done

Fetch once and filter locally instead of calling per item:

bb pr list --json --jq '.pullRequests[] | select((.author.nickname // .author.display_name) == "alice")'

Git integration

Clone fails

bb repo clone runs git clone [email protected]:<workspace>/<repo>.git (or the HTTPS URL with --protocol https) and shows git’s own output as it runs:

[email protected]: Permission denied (publickey).
fatal: Could not read from remote repository.
✗ git clone failed with exit code 128; see git's output above

That is an SSH problem, not a bb auth problem. The CLI does not pass its token to git.

ssh -T [email protected]                                  # verify your key
bb repo clone myworkspace/myrepo --protocol https         # HTTPS instead
bb config set gitProtocol https                           # make HTTPS the default

Command-specific issues

Destructive commands fail instead of asking

✗ This will permanently delete myworkspace/old-repo.
Use --yes to confirm.

These commands only ask Continue? (y/N) in an interactive terminal. You get this error instead when stdin or stdout is piped or redirected, under --json or --no-input, or when BB_PROMPT_DISABLED is set. This affects bb repo delete, bb repo default-reviewers remove, bb repo downloads delete, bb pr comments delete, bb snippet delete, bb snippet comments delete, bb webhook delete, bb branch-restriction delete, bb ssh-key delete, and bb gpg-key delete. Pass the flag:

bb repo delete myworkspace/old-repo --yes

Pull request creation is rejected

A missing title is caught locally, before any request:

✗ Pull request title is required. Use --title option.

Everything else is Bitbucket’s own message, with any error.fields detail flattened in, for example:

✗ Bad request (type: extra keys not allowed)

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

Merge is rejected

Bitbucket returns the reason in the error message. Diagnose the rest without leaving the terminal:

bb pr checks 42     # failing builds
bb pr view 42       # reviewer approvals and merge state
bb pr activity 42   # who requested changes

Common blockers are merge conflicts, unmet required approvals, and failing build checks. Inspect repository rules with bb branch-restriction list --all. To wait for running builds first, use bb pr checks 42 --watch; it exits non-zero if a check failed. For a stricter merge gate, see the auto-merge recipe.

Diff shows nothing

bb pr diff 42
# (empty output)

The PR has no file changes, or the API returned an empty diff.

bb pr view 42        # check state and branches
bb pr diff 42 --web  # compare against the web UI

Typos and “Did you mean?”

bb suggests a correction when a command name or an option value is close to a valid one:

bb prr
# ✗ unknown command 'prr'
# (Did you mean pr?)

bb pr lst
# ✗ unknown command 'lst'
# (Did you mean list?)

bb pr list --state opne
# ✗ --state must be one of: OPEN, MERGED, DECLINED, SUPERSEDED
# (Did you mean OPEN?)

Option values ignore case, so --state open works the same as --state OPEN.

Use bb help <command> (or bb <command> --help) to see a command’s valid values.

`--json` must come after the subcommand

--json takes an optional field list, so it swallows the next word if you put it first:

bb --json pr list

--json did parse, so the failure comes back as a JSON envelope on stderr:

{"name":"BBError","code":5002,"message":"--json consumed 'pr' as its field list, so 'list' was parsed as a top-level command.\nPut --json after the subcommand: bb pr list --json"}

bb --json=id,title pr list works, because the --flag=value form does not eat the next token.

`--jq` needs `--json`

bb pr list --jq '.pullRequests[].title'
# {"name":"BBError","code":8002,"message":"--jq requires --json"}

The error is a JSON envelope on stderr, since --jq asks for machine-readable output. bb api is the one exception: it accepts --jq on its own.

bb pr list --json --jq '.pullRequests[].title'   # correct
bb api /repositories/my-ws --jq '.values[].name' # allowed without --json

`--jq` prints a result but does not exit on Windows

We reproduced this with Bun 1.3.14 on Windows. The jq result appears, but the process can remain alive indefinitely. The npm package now requires Bun 1.4.2 or newer for --jq on Windows. Check bun --version, then run bun upgrade if needed. Standalone Windows binaries include their own Bun runtime.

Empty `--json` field list

bb pr list --json ""

{"name":"BBError","code":8002,"message":"--json field list cannot be empty"}

--json ,, fails the same way. Use bare --json for the full envelope.

Failures that tell you the next step

401, 403, and 404 failures append an actionable line beneath the error:

bb repo list -w does-not-exist
# ✗ No workspace with identifier 'does-not-exist'.
# Verify the id or slug you passed, and that --workspace/--repo point at the right repository your token can see.

A 401 points you at bb auth login; a 403 suggests checking permissions and scopes and links Token Scopes. In --json mode the same text arrives as a hint field. See Error codes for the full list.

Getting debug information

When reporting an issue, gather this:

# CLI version
bb --version

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

# Bun version (npm installation only)
bun --version

# Auth status (never prints the token; use bb auth token for that)
bb auth status

# Config (masks secrets)
bb config list

bb auth status makes a live GET /user call, so it also fails when the network or proxy is the real problem.

Still need help?

Check the FAQ for questions that come up often
Search existing issues
Open a new issue with:
- CLI version (bb --version)
- Operating system
- Complete error message
- Steps to reproduce