CircleCI "pipeline parameter not defined" - Fix Parameters
Your config references a pipeline parameter that was never declared, or one was passed in with the wrong type. Pipeline parameters must be declared under top-level parameters: before pipeline.parameters.* can use them.
What this error means
Validation fails saying a pipeline parameter is not defined, or an API-triggered pipeline is rejected for passing an undeclared parameter. The config never compiles because the parameter reference has no declaration to bind to.
Config is invalid:
- pipeline parameter 'deploy_env' is not defined
- parameter 'run_e2e' expected type 'boolean' but got 'string'Common causes
Parameter used but never declared
Referencing << pipeline.parameters.deploy_env >> requires a matching entry under the top-level parameters: block. Without it, the reference is undefined.
Type mismatch on a passed value
Each parameter declares a type (string, boolean, integer, enum). Passing "true" to a boolean, or a value outside an enum, fails validation.
API trigger sends an undeclared parameter
A pipeline triggered via the API (or a continuation) can only set parameters that are declared. Sending an extra key is rejected.
How to fix it
Declare pipeline parameters with types and defaults
version: 2.1
parameters:
deploy_env:
type: enum
enum: [staging, production]
default: staging
run_e2e:
type: boolean
default: false
workflows:
ci:
jobs:
- deploy:
env: << pipeline.parameters.deploy_env >>Pass matching types from the API
When triggering via the API, send only declared parameters with the right JSON types.
curl -X POST https://circleci.com/api/v2/project/gh/org/repo/pipeline \
-H "Circle-Token: $TOKEN" -H "Content-Type: application/json" \
-d '{"parameters":{"deploy_env":"production","run_e2e":true}}'How to prevent it
- Declare every pipeline parameter you reference, with an explicit type.
- Give parameters sensible defaults so triggers without them still resolve.
- Pass only declared parameters (and correct types) from API triggers.