Bitbucket Custom Service Not Defined Under "definitions"

A step listed a service by name, but there is no matching definitions: services: entry to tell Bitbucket which image to run - so the reference cannot resolve.

What this error means

The pipeline fails configuration noting a named service is not defined. Built-in names like docker resolve automatically, but any custom service must be declared first.

Configuration error: the service "mysql" referenced in step
"Tests" is not defined under definitions > services.

Common causes

Custom service referenced but never declared

A step services: [ mysql ] needs a definitions: services: mysql: block giving the image. Without it, the name has no definition to bind to.

Name mismatch between step and definition

A typo - mysql in the step vs my-sql in definitions - leaves the referenced name undefined even though a similar one exists.

How to fix it

Declare the service in definitions

Add a definitions: services: entry with the image, then reference it by the exact same name.

definitions:
  services:
    mysql:
      image: mysql:8
      variables:
        MYSQL_DATABASE: app_test
        MYSQL_ROOT_PASSWORD: test
pipelines:
  default:
    - step:
        services: [ mysql ]
        script: [ ./test.sh ]

Match names exactly

1. Compare the name in the step’s services: list with the key under definitions: services:.
2. Make them identical, including hyphens and case.
3. Re-validate before pushing.

How to prevent it

• Define every custom service under definitions: services: before referencing it.
• Keep service names consistent between definition and step.
• Reserve built-in names (docker) for their built-in meaning.

Related guides