Bitbucket Pipelines Variable Not Set / Empty in a Step
A command read a pipeline variable that came back empty. The variable is undefined, scoped to a different environment, or not exposed on this trigger (e.g. forks) - so it expands to nothing.
What this error means
A step fails or misbehaves because a $VAR is blank: a deploy targets an empty URL, an auth header is missing a token, or a script branch never matches. Echoing the variable shows it unset only in this context.
+ deploy --host "$DEPLOY_HOST"
Error: --host is required (received empty value)Common causes
Variable defined in the wrong scope
A variable set on a deployment environment is only available to steps with that deployment:. A repository/workspace variable referenced from the wrong place comes back empty.
Secured variables not exposed to the trigger
Secured variables are not passed to pipelines triggered from forked-repository pull requests, so steps that rely on them see empty values there.
How to fix it
Define the variable at the right scope
- Decide whether the variable is repository-wide, workspace-wide, or environment-specific.
- For deploy-only secrets, add them under Repository settings → Deployments for that environment.
- Ensure the step that needs an environment variable declares the matching
deployment:.
Fail fast on missing variables
Assert required variables early so the failure is obvious rather than a confusing empty value downstream.
script:
- test -n "$DEPLOY_HOST" || { echo "DEPLOY_HOST is not set"; exit 1; }
- deploy --host "$DEPLOY_HOST"How to prevent it
- Scope variables deliberately: repo, workspace, or deployment environment.
- Assert required variables at the top of a step.
- Remember secured variables are withheld from forked-PR pipelines.