Cause: The inputs array for a task is empty or the glob doesn't match any files.
Fix: Verify the globs match your source files. variant uses fast-glob internally and ignores node_modules/, .git/, and .variant/. Use find to approximate the same check:
# macOS / Linux
find src -type f
# The exact pattern variant uses (excludes node_modules, .git, .variant):
find . -path ./node_modules -prune -o -path ./.git -prune -o -path ./.variant -prune -o -name '*.ts' -printThen check your config:
tasks: {
build: {
inputs: ["src/**/*", "package.json"], // must match at least one file
},
},An empty inputs: [] means the task never hashes — it will always be a cache miss.
Cause: The binary isn't on PATH. variant is installed as a local dev dependency.
Fix: Run it through npx with the package name (never npx variant, which fetches an unrelated package):
npx @blzsky/variant buildOr add a script to package.json, where the local variant binary is on PATH:
{
"scripts": {
"build:cached": "variant build"
}
}Cause: variant looks for variant.config.ts, variant.config.mjs, variant.config.js, or variant.config.json, in that order, in the current working directory.
Fix: Create the config with variant init --tasks, or check you're running from the project root. Only the task runner (build, run, insight) needs a config; impact, pr and workspace check work without one.
Cause: workspace.enabled is not set to true, or the workspace manifest isn't in the expected location.
Fix: Enable workspace mode and verify your workspace manifest:
workspace: {
enabled: true,
}variant looks for, in order:
pnpm-workspace.yaml(pnpm)package.jsonworkspacesfield (npm / Yarn)- the directories
packages/*,apps/*andservices/*
A package directory also needs a package.json with a name. Run variant env to see what was detected.
Cause: Git is disabled, the base ref doesn't point to the expected commit, or .git isn't accessible from the working directory.
Fix: Check git config:
git: {
enabled: true,
baseRef: "origin/main", // adjust to match your branching strategy
},Run git diff --name-only origin/main manually to verify the diff is what you expect — this is the exact command variant runs internally with that baseRef.
Cause: The package's package.json doesn't declare the changed package as a dependency, so the cascade doesn't reach it.
Fix: Ensure the dependent package lists the changed package in dependencies or devDependencies in its own package.json. variant's cascade walks workspace dependency edges, not just dependsOn in the task graph.
Cause: The config failed Zod validation, usually due to an unknown task referenced in dependsOn or a typo in a field name.
Fix: The error message includes the exact path. Example:
[✗] Config validation failed
→ tasks.test.dependsOn: references unknown task "builds" — add it to config.tasks or remove the reference
Check that every task name in dependsOn matches a key in tasks.
When a task fails, variant adds a short block explaining why that task was selected to run:
[TASK_EXECUTION_ERROR] Task "web:build" failed with exit code 1
ran because: packages/api/src/db.ts changed
also affected: web:test, web:typecheck
Hint: Check the output above, fix the failing command in task "web:build", then re-run.
ran because: is one of three answers:
| Line | Meaning |
|---|---|
<files> changed |
The current diff touched these files, which put the task in scope. |
cache miss — inputs hash <a>, cached <b> |
The task's inputs hashed differently than the cached run. |
cache miss — nothing cached for this task yet |
A first run, not an invalidation — there was nothing to compare against. |
this task is never cached, so it runs every time |
The task has no inputs, or strategy: "strict" opts it out of caching. See issue 1 above. |
also affected: lists the other tasks this run invalidated. It appears only when there are any.
This does not explain why the task failed. It answers "why did this run at all", which is a different question. A task can be selected because db.ts changed and then fail for a reason with nothing to do with db.ts — treat the file list as a place to start looking, not a cause. The failing command's own output, above the block, is the actual evidence.
The block appears on stderr, only on failure, and only for errors belonging to a task — config and usage errors have no task to explain. Colors follow the same rules as the rest of the CLI (NO_COLOR, --no-color, FORCE_COLOR); when styling is off the same text still prints.
Cause: The --base ref does not resolve, or, for pr check and pr report, it shares no merge base with HEAD. In CI this is the usual case, for two reasons:
actions/checkoutfetches a single commit by default, so the base commit is not there to compare against.- It creates no local branch for the target, so
--base mainnames nothing.
Locally, the default --base HEAD~1 fails the same way in a repository with a single commit.
Fix: Check out with fetch-depth: 0 and pass the remote-tracking ref:
- uses: actions/checkout@v7
with:
fetch-depth: 0
- run: npx --yes @blzsky/variant pr check --base origin/mainLocally, git rev-parse --verify <ref> confirms a ref exists. The example workflows are set up correctly. See Refs and diffs for how each command compares.
Cause: impact found no test file. It indexes *.test.* and *.spec.* in TypeScript and JavaScript, and anything under a __tests__/ directory. Tests named another way (*.cy.ts, *.e2e.ts), and JavaScript tests that git ignores, are not counted. It stops rather than printing "0 of 0 tests", which would read as "run nothing".
Fix: Rename the tests to a pattern above, or run impact from the directory that holds the tests.
Run variant doctor — it checks the most common issues automatically. If the problem persists, open an issue at github.com/saintparish4/variant with the output of:
variant doctor
variant env