Start here: which Bitbucket layer is failing?
Bitbucket Cloud failures fall into three layers, and conflating them is the main reason debugging drags: a pipeline problem (it never ran, or it ran and failed), a merge problem (a conflict, an unmet check, or a branch restriction), and an auth problem (a 401 from a deprecated credential or a missing scope). Decide which layer you are in first, because the diagnostics do not overlap — a pipeline that never triggers is a YAML/trigger question, a blocked merge is a checks/restrictions question, and a 401 is a credentials question. This guide is the methodology layer; each failure links to a page with the full fix.
The Bitbucket-specific gotcha that cuts across all three: on Cloud, a merge check is only a warning unless you are on Premium with enforcement enabled (Suggest or require checks before a merge). Teams configure checks, see them on PRs, and assume the branch is protected — it is not, until a branch restriction is enforcing them.
Layer 1 — Pipelines: never-ran vs ran-and-failed
These fail in opposite ways. Never ran is silent: nothing errors, the commit just sits there. Ran and failed is loud but often misattributed. Split them first.
No pipeline ran has documented causes (The build was not triggered for a particular commit): no bitbucket-pipelines.yml on that branch, no definition matching the branch, [skip ci] in the message, a push with more than five references, or a webhook larger than 256 KB. And only the HEAD of a push builds, not each commit. A subtle one: branch matching is case-sensitive, so a feature/* pattern will not match Feature/login (Pipelines not triggering for specific branches).
A pipeline ran and failed is usually a resource limit. A step defaults to 4 GB (4096 MB); size: 2x gives 8 GB (8192 MB) (Step options, Databases and service containers), and that memory is shared with service containers (1024 MB each by default) — so over-stuffed services starve the build container and you get "exceeded memory limit." Monthly build minutes are capped by plan — 50 (Free), 2,500 (Standard), 3,500 (Premium) — and an exhausted budget stops every pipeline (Limitations of Bitbucket Pipelines). A step's max-time defaults to 120 minutes (range 1–720); exceeding it fails the build (Step options). The full diagnosis and fixes are in Bitbucket Pipelines failing or not triggering.
Layer 2 — Merge: conflict, check, or restriction
Read the PR's merge panel and route:
- Conflict — the Merge button is unavailable and the PR notes conflicts. Bitbucket Cloud has no in-UI conflict editor — "you can't select the Merge button from the pull request to merge" (Resolve merge conflicts). Resolve locally:
git checkout <feature_branch>
git pull origin <destination_branch> # pull in the conflicting changes
# resolve, then:
git add <resolved_file>
git commit -m "Resolve conflicts with <destination_branch>"
git push origin <feature_branch>
- Check warns but you can still merge — checks are not enforced. On Cloud, "Prevent a merge with unresolved merge checks" is a Premium feature; without it the check is advisory (Suggest or require checks before a merge).
- Merge is blocked on approvals or builds — a branch restriction is enforcing it; merge checks and branch permissions "work in tandem" (Configure branch restrictions).
The configurable checks are minimum approvals, minimum approvals from default reviewers, no changes requested, no unresolved tasks, and a minimum number of successful builds (Suggest or require checks before a merge). Note the "minimum successful builds" check reads the commit build status from Pipelines — so a Layer 1 failure becomes a Layer 2 block. Full walkthrough: Bitbucket pull request will not merge.
Layer 3 — Auth: the 2026 app-password removal
If a credential that used to work now returns 401, in 2026 it is most likely a deprecated app password. New app passwords could not be created after 9 September 2025, brownouts began 9 June 2026, and they are permanently removed 28 July 2026 — after 9 June 2026, API tokens are the only way to use Basic auth (Using app passwords, 401 while authenticating). Migrate to a scoped API token or an access token — do not regenerate the app password.
The other 401 cause is a missing scope. API tokens carry granular scopes set at creation: read:repository:bitbucket, read:pullrequest:bitbucket, and read:pipeline:bitbucket for reading repos, PRs, and pipelines respectively (API token permissions). A token missing read:pipeline:bitbucket reads repos and PRs but 401s on pipelines — which looks like a partial outage, not an auth gap. Full diagnosis: Bitbucket Cloud API 401.
If requests return 429, you hit the rate limit — 1,000/hour per authenticated user over a rolling hour, scaling to a 10,000/hour ceiling for large paid workspaces using access tokens (API request limits).
Recommended approach (with tradeoffs)
- For pipelines: keep branch patterns explicit and case-correct, cache dependencies, and right-size service containers so a 1x step has enough shared memory. Raising
sizeis the fast fix but burns minutes faster; trimming services and caching is cheaper long-term. The blast radius of an exhausted minute budget is every pipeline on the plan, not just the noisy repo. - For merges: if checks must actually block, budget for Premium enforcement plus a matching branch restriction — advisory warnings will not stop a distracted merger. The tradeoff is a stricter workflow where a flaky build genuinely blocks shipping.
- For auth: use a workspace/repository access token for services, not a personal credential. It survives offboarding and qualifies for the scaled rate limit; the cost is admin-level issuance and rotation. And migrate off app passwords now — that break is scheduled, not hypothetical.
Validation
# Auth + scope check: a 200 on both proves repository AND pipeline read scopes.
curl -s -u "$ATLASSIAN_EMAIL:$API_TOKEN" \
"https://api.bitbucket.org/2.0/repositories/{workspace}/{repo}/pipelines/{uuid}" \
-o /dev/null -w '%{http_code}\n'
For a triggering fix, push a trivial commit and confirm a run appears in the Pipelines list within seconds. For a merge fix, confirm the conflict banner is gone, every check is satisfied, and the most recent commit shows a successful build status.
Operational lessons
The three layers mislead in different directions. A pipeline that never triggers is silent — the commit sits there and people assume it passed. A merge check that only warns gives false confidence — the branch looks protected but is not. And an app-password 401 is a scheduled break — an integration that worked for years fails on a date because Atlassian retired the credential, not because your code changed.
The connective tissue across all three is the same chain: a commit triggers a pipeline, the pipeline's status gates a merge check, and the merge check (when enforced) blocks the PR. A failure anywhere in that chain surfaces somewhere else — a memory-killed build becomes a stuck merge two layers up. Following the chain end to end — commit → pipeline → merge check → PR — is consistently faster than treating the failed build and the blocked merge as separate tickets, which is exactly the cross-system correlation that turns "Bitbucket is broken" into "this commit's pipeline ran out of memory, so its build status is missing, so the merge check never went green."