GitLab "configuration is invalid: variable" Errors

By Kaveh Alemi·Latchkey

GitLab rejected the config because a variables entry is malformed - the wrong type, an invalid name, or a value that is not a string or expandable scalar.

What this error means

Validation fails naming the variables block: a value that should be a string is a map or list, or a variable name uses characters GitLab does not allow. No pipeline runs until it is fixed.

gitlab-ci

This GitLab CI configuration is invalid:
variables config should be a hash of key-value pairs, value can be a hash

Diagnose it: which rule matched, and on which runner?

GitLab evaluates rules: top to bottom and the first match wins, including one that sets when: never. A job that does not run, or runs when you did not expect it to, is nearly always matching an earlier rule than the one you are reading.

.gitlab-ci.yml

# validate the definition against the project
curl -s --header "PRIVATE-TOKEN: $TOKEN" \
  "https://gitlab.com/api/v4/projects/$CI_PROJECT_ID/ci/lint" \
  --data-urlencode "content=$(cat .gitlab-ci.yml)"

# what the job actually sees
script:
  - env | grep -E "^CI_(PIPELINE_SOURCE|COMMIT_REF_NAME|RUNNER)" | sort

Common causes

Non-string or malformed value

A variable value given as a raw list, or a nested map missing the value: key when using the descriptive form, fails the schema.

Invalid or reserved variable name

Variable names must match GitLab's allowed pattern. A name with spaces, leading digits, or an illegal character is rejected.

How to fix it

Use string values (or the descriptive hash form)

.gitlab-ci.yml

variables:
  DEPLOY_ENV: "staging"
  TIMEOUT: "30"
  REGION:
    value: "us-east-1"
    description: "Deployment region"

Fix the variable names

Use only letters, digits, and underscores; do not start a name with a digit.
Quote numeric or boolean-looking values so they stay strings.
Re-validate in the Pipeline Editor after correcting names and types.

How to prevent it

Always quote numeric and boolean variable values.
Keep variable names alphanumeric with underscores.
Validate the variables block in the editor before merging.

Frequently asked questions

What causes GitLab "configuration is invalid: variable" errors?

There are 2 common causes: non-string or malformed value and invalid or reserved variable name. A variable value given as a raw list, or a nested map missing the value: key when using the descriptive form, fails the schema.

How do I fix GitLab "configuration is invalid: variable" errors?

There are 2 fixes depending on which cause you have: use string values (or the descriptive hash form) and fix the variable names. Work through them in order, since the first is the most common.

What does GitLab "configuration is invalid: variable" errors actually mean?

Validation fails naming the variables block: a value that should be a string is a map or list, or a variable name uses characters GitLab does not allow.

How do I stop GitLab "configuration is invalid: variable" errors happening again?

Always quote numeric and boolean variable values. The prevention section lists 3 changes that keep it from recurring.

References

GitHub Actions documentation