Missing required environment variable

What this failure means

A required environment variable was not set in the CI environment. The job cannot continue without the expected configuration or secret value.

Symptoms

Faultline looks for one or more of these log fragments:

environment variable not set
required env var
missing required variable
unbound variable
please set the
token is empty
api key is empty
secret is empty

Diagnosis

A required environment variable was not set in the CI environment. The job cannot continue without the expected configuration or secret value.

Fix steps

1. Identify the missing variable name from the error and add it to your CI provider:

   • GitHub Actions: Settings › Secrets and variables › Actions.
   • GitLab CI: Settings › CI/CD › Variables (check the Protected flag).
   • CircleCI: Project Settings › Environment Variables or the context.
   • Bitbucket Pipelines: Repository settings › Repository variables.

2. Reference the variable in the workflow file with the correct name — names are case-sensitive.

3. For GitHub Actions: secrets are withheld from fork PRs by default. If the job runs against a fork, move secret-consuming steps to a post-merge job or use pull_request_target with caution.

4. Verify the variable is actually exported at runtime (use a non-sensitive variable to test wiring):

   echo "VAR set: $(test -n "$VAR_NAME" && echo yes || echo NO)"
   

5. Check that repository forks and non-default branches have access to the required secrets and are not blocked by protection rules.

Validation

• Add a diagnostic step confirming availability without revealing the value.
• Re-run the failing step and confirm the empty-variable error is gone.

Why it matters

Environment variables that hold secrets (tokens, API keys, passwords) must be configured explicitly in CI settings. They are not inherited from the local developer environment and are not committed to the repository.

Prevention

• Document all required environment variables in a .env.example file.
• Add a validation step at the start of each CI job that checks for required variables.
• Use a secrets manager or vault integration to avoid manual secret management.

Try it locally

echo "VAR set: $(test -n "$VAR_NAME" && echo yes || echo NO)"
echo "VAR set: $(test -n "$VAR_NAME" && echo yes || echo NO)"

How Faultline detects it

Use faultline explain missing-env to see the full playbook.

faultline analyze build.log
faultline explain missing-env

Generated from playbooks/bundled/log/auth/missing-env.yaml. Do not edit directly.