Bitbucket Pipe Variables - Wrong Array/Multiline Variable Syntax

Some pipe inputs are arrays (a list of values), not scalars. Passing a single string where the pipe wants a list - or the reverse - makes the pipe reject or misread the input.

What this error means

A pipe errors that a variable is the wrong type or cannot be parsed, even though it is set. The value is passed as a scalar where the pipe expects an array (or a comma-joined string that the pipe does not split).

Error: variable "EXTRA_ARGS" expected a list but received a string.
✖ pipe failed (atlassian/...:x.y.z)

Common causes

Array variable passed as a scalar

Pipes that take list inputs expect YAML array syntax. A single string value where the pipe wants [ a, b, c ] fails type validation.

Multiline value not formatted correctly

A long or multiline value (a script, a JSON blob) needs proper YAML block scalar formatting; a flat string can be truncated or misparsed by the pipe.

How to fix it

Pass list inputs as a YAML array

Use the array form the pipe documents for list variables.

- pipe: atlassian/some-pipe:1.0.0
  variables:
    COMMANDS:
      - "build"
      - "test"
    EXTRA_ARGS: [ "--verbose", "--fail-fast" ]

Use block scalars for multiline values

Format multiline input with a YAML block scalar so it reaches the pipe intact.

variables:
  SCRIPT: |
    echo "line 1"
    echo "line 2"

How to prevent it

• Read each pipe variable’s expected type (scalar vs array) in its docs.
• Use YAML array syntax for list inputs.
• Use block scalars (|) for multiline values.

Related guides