(Breaking Change) Undeclared Parameters Will Fail Config Compilation

Build Environment
1

On July 8th, 2026, CircleCI is updating how undeclared parameters are handled. Previously, referencing a parameter that is not declared in the current scope could silently resolve instead of raising an error, allowing invalid configs to compile.

After this date, any config that references an undeclared parameter will fail to compile with an undeclared-parameter error.

Background

This corrects a long-standing issue where invalid configs were silently accepted. As we build the next generation of config tooling, stricter and more predictable validation ensures more reliable config.

Pipeline parameters can only be resolved in the config file in which they are declared. Currently, there are niche cases when a reference points to a parameter that isn’t declared or in scope, the config compiles anyway, and the reference silently resolves to null instead of failing. This can lead to unintentional, difficult to troubleshoot behaviour

A common example

In this example, the config is invalid because orbs cannot use pipeline parameters:

yaml

version: 2.1

parameters:
  bug:
    type: string
    default: "this is buggy"

orbs:
  buggy-orb:
    jobs:
      exhibit-bug:
        docker: [image: "python:2.7"]
        parameters:
          bug:
            type: string
            default: << pipeline.parameters.bug >>
        environment:
          FOO: << parameters.bug >>
        steps:
          - checkout

workflows:
  build-test-deploy:
    jobs:
      - buggy-orb/exhibit-bug

Today, this compiles and FOO resolves to null. After the change, it will fail to compile.

How to check and fix your config

You can preview whether your config is affected today, before the change is enabled.

  1. Validate your config using either:

    • UI: open the config editor and enable the “config next” toggle (bottom-right). It will re-validate your config automatically (this may take a moment).

    • CLI: first install or update to the latest version of the CircleCI CLI (see Installing the CircleCI local CLI), then run circleci config validate <path-to-config> --next.

  2. Review the errors — look for undeclared-parameter errors in the output.

  3. Fix them — remove references to parameters that aren’t declared in the current scope, or declare the parameter where it’s used.

  4. Revalidate using the same UI toggle or CLI command to confirm the errors are resolved.

Need help?

If you have questions or run into issues migrating, reply to this thread or open a support ticket.