Bitbucket Pipelines "Configuration error" in bitbucket-pipelines.yml

By Kaveh Alemi·Latchkey

Bitbucket validated your bitbucket-pipelines.yml against its schema before running anything and found a structural problem. No build runs until the file is valid.

What this error means

The pipeline result page shows a "Configuration error" with a message pointing at a section of bitbucket-pipelines.yml. Nothing executes - the error appears immediately, before any step is scheduled.

Configuration error
There is an error in your bitbucket-pipelines.yml file. Please check
the following: "pipelines > default > 0 > step" is required.

Common causes

A required key is missing or misplaced

Every pipeline needs at least one step, and steps live under a pipeline section like default, branches, or pull-requests. A script placed directly under a pipeline, or a missing step, fails validation.

An unknown or misspelled key

Bitbucket only accepts a fixed set of keys (image, pipelines, definitions, options, clone, …). A typo like pipline: or steps: (it is step:) is rejected as invalid configuration.

How to fix it

Validate against the canonical structure

Each step must sit under a pipeline section and contain a script. Match this shape exactly.

pipelines:
  default:
    - step:
        name: Build
        script:
          - echo "building"

Use the online validator

1. Open the Bitbucket Pipelines validator (Repository settings → Pipelines, or the in-editor validator).
2. Paste your file - it reports the exact failing path (e.g. pipelines > default > 0 > step).
3. Fix the named path and re-validate before pushing.

How to prevent it

• Validate bitbucket-pipelines.yml in the online validator before committing.
• Keep a known-good template and edit from it rather than from memory.
• Use an editor schema/plugin that flags unknown keys as you type.

Frequently asked questions

Related guides

References

• GitHub Actions documentation