GitHub Actions Reusable Workflow Input Type Mismatch
A reusable workflow declares an input as boolean or number, but the caller passes a quoted string (or a string expression), and the strict workflow_call typing rejects or mis-evaluates it.
What this error means
The caller fails validation with a type error, or the called workflow treats a boolean input as an always-truthy string, so an if: inputs.flag check behaves incorrectly.
# called workflow declares: enabled: { type: boolean }
# caller passes a string, which is not a boolean
with:
enabled: 'true' # rejected or treated as a string, not a real booleanDiagnose it: print the context before you change anything
Most workflow-expression bugs are not syntax errors, they are an expression reading something that is empty. GitHub resolves a missing property to an empty string instead of failing the run, so a wrong reference looks like a logic bug rather than a mistake. Dump the contexts first and you will usually see the answer immediately.
- name: Dump contexts
run: |
echo '--- github ---' ; echo '${{ toJSON(github) }}'
echo '--- needs ---' ; echo '${{ toJSON(needs) }}'
echo '--- steps ---' ; echo '${{ toJSON(steps) }}'
echo '--- matrix ---' ; echo '${{ toJSON(matrix) }}'
echo '--- inputs ---' ; echo '${{ toJSON(inputs) }}'Check the context is allowed where you used it
Contexts are not available everywhere. The same expression can be valid in a step if and invalid in a job if, which is why an expression that works in one workflow fails when moved.
| Where you wrote it | Contexts available there |
|---|---|
run-name | github, inputs, vars |
concurrency | github, inputs, vars |
Top-level env | github, secrets, inputs, vars |
jobs.<id>.if | github, needs, vars, inputs |
jobs.<id>.steps.if | github, needs, strategy, matrix, job, runner, env, vars, steps, inputs |
jobs.<id>.outputs | Full access, including secrets |
Reusable workflow outputs | github, jobs, vars, inputs |
Common causes
String passed to a typed input
workflow_call inputs are strictly typed as string, boolean, or number. Passing a quoted string to a boolean input does not coerce cleanly and an if check on it can be wrong.
Expression result is a string
Any ${{ }} expression yields a string. Feeding it to a boolean or number input requires the called workflow to interpret it, or a fromJSON to coerce.
How to fix it
Pass the correct literal type
# caller
with:
enabled: true # real boolean literal
retries: 3 # real number literalCoerce expression results explicitly
When a value comes from an expression, convert it to the declared type with fromJSON.
with:
enabled: ${{ fromJSON(steps.flags.outputs.enabled) }} # "true" -> boolean trueCatch it before it reaches CI
Every failure in this cluster is statically detectable. actionlint parses workflow expressions, checks context availability against the same rules above, and validates needs references, so these bugs never need to cost you a run.
# one-off
docker run --rm -v "$(pwd):/repo" --workdir /repo rhysd/actionlint:latest -color
# as a job, before anything expensive runs
- uses: actions/checkout@v4
- run: |
bash <(curl -s https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash)
./actionlint -colorHow to prevent it
- Declare each workflow_call input with the type it truly is.
- Pass boolean and number literals unquoted from the caller.
- Use fromJSON to coerce expression results to boolean or number.