GitHub Actions "The template is not valid: invalid programming construct"

Workflow ${{ }} expressions support a limited grammar. Using an unsupported operator, statement, or nesting that the template engine cannot evaluate yields an "invalid programming construct" error.

What this error means

The workflow fails to start with "The template is not valid: ... invalid programming construct", pointing at a complex or malformed expression.

Error: The template is not valid. .github/workflows/ci.yml (Line: 14, Col: 11): The directive 'invalid' is not allowed in this context. Invalid programming construct.

Common causes

Unsupported expression operator/construct

The expression used something outside the supported functions/operators (an unknown directive or statement form).

Malformed nested expression

Mismatched braces or improperly nested ${{ }} produced an unparseable construct.

How to fix it

Use only supported expression syntax

1. Rewrite the logic with supported functions (contains, fromJSON, format).
2. Move complex logic into a run step instead of the expression.
3. Check brace matching and nesting in ${{ }}.

# move complex logic into a script, expose a simple output
- id: gate
  run: echo "go=true" >> "${GITHUB_OUTPUT}"
- if: steps.gate.outputs.go == 'true'
  run: make deploy

How to prevent it

• Keep ${{ }} expressions within the supported grammar.
• Push complex conditionals into run steps with outputs.
• Lint expressions with actionlint.

Related guides