dorny/paths-filter Outputs Always False - Causes & Fixes
dorny/paths-filter reports every filter as false (or true) because it cannot compute the changed-file set - usually a checkout without enough history, or a base it cannot diff against.
What this error means
Downstream steps gated on steps.filter.outputs.<name> never run (or always run). The filter step succeeds but its boolean outputs do not reflect the actual file changes.
- uses: dorny/paths-filter@v3
id: filter
# later: steps.filter.outputs.src is always 'false'
# because the diff base could not be resolved on a push eventDiagnose 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
No base ref to diff against
On push events the action diffs against the before commit; on a force-push or first commit, or with a shallow clone lacking that ref, it cannot compute changes and returns false.
Missing step id or mismatched filter keys
Outputs are read as steps.<id>.outputs.<filter>. Without an id on the step, or with a filter name that does not match what you reference, the condition reads an empty value.
How to fix it
Give the step an id and define filters
- uses: actions/checkout@v4
- uses: dorny/paths-filter@v3
id: filter
with:
filters: |
src:
- 'src/**'
- if: steps.filter.outputs.src == 'true'
run: npm testProvide a base for events without one
- On pull_request the action diffs against the PR base automatically.
- For push on the default branch, set base to the branch so it diffs against the prior commit.
- Avoid overly shallow checkouts that drop the commit the diff needs.
Catch 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
- Always give paths-filter a stable id and compare outputs to the string "true".
- Set an explicit base for push events on the default branch.
- Prefer pull_request events where the diff base is unambiguous.