Diagnosing Missing or Failing Custom Tasks in Nimble

The problem and the fix in one paragraph

You run nimble test in a Nim project and receive an unknown command error, or nimble tasks prints nothing, even though the task is written in the project's .nimble file. This usually appears after a fresh clone, a manifest refactor, or a move to CI. The useful takeaway: most missing-task problems are caused by working directory, manifest syntax, name collisions, or missing tools—not a broken Nimble installation.

Recognizable condition

You are in a Nim project and run nimble test or another custom task name. Nimble replies that the command is unknown or invalid, or it does nothing at all. Running nimble tasks either lists no tasks or omits the task you expect. The same project may work on your laptop but fail in CI. Nimble is Nim's package manager. A .nimble file is the project manifest that declares metadata and named tasks. A task is a named block that bundles one or more shell commands under an exec line.

Cause and diagnostic table

Symptom	Most likely cause
You are not in the project root	Nimble reads only ./project.nimble by default
Manifest exists but nimble tasks is empty	Malformed task block or missing exec body
Task name matches a built-in	Collision with install, build, or test
Task starts and fails immediately	Missing tool on PATH or failing hook

Ordered checks

1. Confirm the current directory contains exactly one .nimble file. Run ls *.nimble or dir *.nimble on Windows. If there are zero or multiple files, change to the project root.
2. Run nimble tasks and compare its output with the task names in the manifest. If the list is empty, the manifest is not being read or the tasks are not parsing.
3. Re-run the failing task with verbose output: nimble -v test. Look for the first error line. Error wording varies by version, so match on the failure mode rather than exact strings.
4. Open the .nimble file and check for syntax errors. Confirm each task has a name, a desc field, and an exec body. Rename any task that collides with a built-in command such as install, build, or test.
5. Verify that every external command the task shells out to resolves in the same shell. On POSIX run which nim; on Windows run where nim. If the tool is missing, install it or correct PATH.
6. Inspect before and after hook blocks. A failing hook can abort a task before its exec body runs. Temporarily comment out hooks to isolate the problem.

Fixes tied to findings

• Wrong directory: run commands from the project root.
• Malformed manifest: correct indentation, punctuation, and block structure. Keep a backup copy before editing; if the edit makes things worse, restore from backup or run git checkout -- project.nimble.
• Name collision: rename the task to something that does not shadow a built-in, for example from test to run-tests.
• Missing exec body: add exec "command" inside the task block.
• Failing hook: fix the hook command or remove it during diagnosis.
• Missing toolchain: install nim, git, or a C compiler and confirm it appears in PATH.

After each fix, confirm by running nimble tasks and then nimble test.

Concrete example

The following is an illustrative manifest. Exact punctuation varies by nimble version, so verify against your installed release.

task test, "desc": "Run the test suite"
  exec "nim test"

If nimble tasks lists test and nimble test executes the suite, the manifest is syntactically valid for your version.

Escalation criteria

File an upstream issue when:

• A minimal manifest containing one trivial task still fails.
• Verbose output shows an internal error or traceback.
• Identical manifests behave differently locally versus in CI.

Include nim --version, nimble --version, your operating system, the .nimble file, and verbose output.

Limitations and how to check the result

Error message wording varies by nimble release. On Windows, task commands run through cmd.exe, so quoting and available utilities differ from POSIX shells; do not assume bash-isms. Avoid registry-mutating commands such as publishing while diagnosing.

Practical check: create a scratch project with nimble init, add one task, and confirm nimble tasks lists it and nimble test executes it. Then reproduce the failure in a clean checkout of the real project and re-check after each fix. Compare nim --version and nimble --version locally versus CI to rule out toolchain drift.