PipelinesFailing

A pipeline that never ran vs one that ran and failed

Split this in two before debugging, because the causes do not overlap. No pipeline ran is almost always a configuration or trigger problem: no bitbucket-pipelines.yml on the branch, no definition matching the branch name, Pipelines not enabled, a [skip ci] in the commit message, a push with more than five references, or an oversized webhook (The build was not triggered for a particular commit). A pipeline ran and failed is usually a step exceeding its memory limit, exhausting the monthly build minutes, or hitting the per-step time limit. Knowing which half you are in tells you whether to read the YAML or read the failed step's log.

Why a pipeline does not trigger

Bitbucket documents the specific reasons a push produces no build (The build was not triggered for a particular commit):

• No matching definition — "There may be no definition on the bitbucket-pipelines.yml file that matches the branch."
• File not on that branch — the YAML exists only on main, not the branch you pushed.
• [skip ci] / [ci skip] in the commit message.
• More than five references in the push — "The push might have more than 5 references (branches, tags)."
• Oversized webhook — "The size of the webhook ... may be larger than 256 Kb."
• Only HEAD builds — "Pipelines will only trigger builds for the HEAD of the current Git push," so intermediate commits in a multi-commit push do not each build.

A separate, easy-to-miss cause is branch-name case sensitivity: "Git is case-sensitive when it comes to branches' names, so Bitbucket Pipelines YAML validator will also take this case sensitivity into consideration" (Pipelines not triggering builds for specific branches). A feature/* pattern will not match a branch pushed as Feature/login.

Why a pipeline fails

Step out of memory. A step defaults to 4 GB (4096 MB) of memory and 4 CPUs; size: 2x gives 8 GB (8192 MB), scaling up through 4x/8x to larger sizes (Step options, Databases and service containers). That memory is shared with service containers — each service defaults to 1024 MB, and the build container keeps the remainder after services are allocated, with a 1024 MB floor. So three 1 GB services on a 1x step leave the build container starved, and the failure shows as "Container ... exceeded memory limit" (Build failed: container exceeded memory limit).

Build minutes exhausted. Monthly minutes are capped by plan: 50 (Free), 2,500 (Standard), 3,500 (Premium) (Limitations of Bitbucket Pipelines). When they run out, pipelines stop running until the next cycle or a plan change.

Time limit hit. A step's max-time ranges 1–720 minutes, default 120; exceeding it fails with "exceeded build time limit" (Step options, exceeded build time limit error).

Diagnose it

For "no build":

1. Confirm bitbucket-pipelines.yml exists on the branch you pushed, not just main.
2. Validate the branch matches a pipelines: definition, with exact case. A feature/* glob will not match Feature/....
3. Check the commit message for [skip ci] / [ci skip].
4. Confirm the push had ≤ 5 references and Pipelines is enabled for the repo.

For "ran and failed": open the failed step in the Pipelines UI and read that step's log — the red step names itself and its exit reason. A memory or time failure is stated explicitly in the log banner. For memory, count your service containers and add their defaults against the step size:

# A 1x step is 4096 MB total. Two 1 GB services leave ~2 GB for the build
# container — bump the size if the build itself needs more.
- step:
    size: 2x            # 8192 MB total instead of 4096 MB
    services:
      - postgres        # defaults to 1024 MB
      - redis           # defaults to 1024 MB
    script:
      - ./run-tests.sh

Resolution options

Trigger problems: add or fix the branch definition so the pattern matches (mind the case), put the YAML on the right branch, remove a stray [skip ci], or split a push that exceeds five references. Enable Pipelines in repo settings if it is off.

Memory: raise the step size (1x → 2x → 4x), or reduce service-container count/footprint so the build container keeps enough of the shared budget. A service you do not need in that step is free memory back.

Time: raise max-time toward the 720-minute ceiling if the work genuinely takes that long, but treat a step creeping toward an hour as a smell — parallelize or cache instead of extending the clock.

Minutes: upgrade the plan for more monthly minutes, or cut waste — caches for dependencies, fewer redundant runs, and [skip ci] on commits that do not need a build all reduce burn.

Recommended approach (with tradeoffs)

For triggering, make branch patterns explicit and case-correct, and keep the YAML on every branch that should build — the cost is a little duplication, the payoff is no silent "why didn't it run." For resource limits, raising the step size is the fast fix but it consumes minutes faster (a larger step bills more), so it trades your minute budget for headroom; the cheaper long-term move is trimming service containers and adding caches so a 1x step is enough. The blast radius of getting this wrong is not data loss — it is a blocked merge (the "minimum successful builds" check never goes green) and a burned minute budget that halts every repo on the plan, not just the noisy one.

Validation steps

• After a YAML fix, push a trivial commit to the branch and confirm a run appears in the Pipelines list within seconds.
• After a size change, re-run and confirm the step completes without the memory banner.
• Check remaining build minutes for the month so a fix does not immediately re-exhaust the budget.

Prevention strategies

• Cache dependencies so steps are faster and cheaper, directly extending how far your monthly minutes go.
• Right-size service containers — only declare the services a step actually uses, since each one carves 1 GB out of the shared step memory by default.
• Alert on build-minute consumption before the cap, not after; an exhausted budget stops every pipeline at once and is invisible until something fails to build.
• Keep branch patterns and case in sync with your naming convention so a renamed branch prefix does not silently stop triggering builds.

Operational lessons

The two halves of this problem fail in opposite ways and mislead differently. "No build" is silent — nothing errors, the commit just sits there, and people assume the pipeline passed. "Build failed" is loud but often misattributed: an out-of-memory kill from over-stuffed service containers reads like flaky test infrastructure until you do the 4096-minus-services arithmetic. Always classify first, then read either the YAML or the failed step's log — not both at random.

Because the "minimum successful builds" merge check depends on a green pipeline, a triggering or resource failure here quietly becomes a blocked PR over in pull request will not merge. The build, the commit that triggered it, and the PR waiting on it are one chain; following it end to end is faster than treating the failed build and the stuck merge as separate tickets.