moon task debugger
A workflow-oriented diagnostic skill for troubleshooting moon tasks. This is not a reference manual
— it guides you through a structured debugging flow so you can isolate the problem quickly.
For conceptual background, see the moon documentation.
Before you start: Ask the user for the <project>:<task> target to debug. If they haven't
provided a specific target, prompt them for it — the diagnostic flow requires a concrete target to
inspect.
Quick-start: 5-step diagnostic flow
Work through these steps in order. Most issues resolve by step 3.
Step 1: Inspect the resolved task configuration
The first thing to check is whether the task is configured the way the user expects. moon merges
configuration from multiple sources (global tasks, project config, inheritance), so the resolved
result can surprise people.
moon task <project>:<task>
moon task <project>:<task> --json
What to verify:
command vs script — if the command contains pipes (|), redirects (>), chained commands
(&&), or complex syntax, it must use script, not command.inputs — are they too broad (**/* captures everything) or too narrow (missing source files)?
Check state.defaultInputs (true = using default **/*) and state.emptyInputs (true =
explicitly set to []). Both keys are omitted from the JSON entirely when false, as is
state.setRunInCi.outputs — are they declared for build tasks? Missing outputs means the cache can never hydrate
artifacts. In v2.3+, outputs also affect the default cacheStrategy of any task that depends
on this one (see Step 4).toolchains — is the correct toolchain(s) assigned? An incorrect toolchain means wrong tool
versions.deps — are task dependencies correct and complete? In v2.3+, each dep entry can carry a
cacheStrategy (hash / ignored / outputs) that controls whether the dep contributes to this
task's cache hash. If omitted, the default depends on whether the dep declares outputs.options — check persistent, runInCI, cache, affectedFiles, mutex, timeout,
retryCount, allowFailure, and os.env — in v2.5+, environment variables can also be inherited from a workspace-level env in
.moon/tasks/**/* (merged into the project's env, project wins), and the project can change the
merge behavior via workspace.mergeStrategies.env. A variable with a surprising value may come
from a layer outside the task.checks v2.4+ — shell scripts that run before the task. Their type determines the
outcome: a requirement failing makes the task fail, all condition checks passing makes the
task skip, and a fingerprint folds script output into the task hash. A surprising fail,
skip, or cache invalidation often traces back to a check.tags v2.3+ — labels for grouping tasks. Affects targets like :#quality and MQL
taskTag queries. If a task isn't matched by a #tag target you expected, check this list.type — build (has outputs), test (default), or run (persistent)preset — server or utility apply multiple option defaults at once.
Red flags:
command: 'eslint . && prettier --check .' — shell syntax in command is a parse error in v2.
Use script instead.- Empty
outputs on a build task — cache will never restore artifacts.
inputs: ['**/*'] — too broad, cache invalidates on every change.- A
persistent task in a deps chain — moon produces a hard error at runtime.
command: 'noop' or nop / no-op — the task is intentionally a no-op and does nothing. moon
treats these specially.runInCI: 'only' — task runs in CI but NOT locally (common surprise).runInCI: 'skip' — task is skipped in CI but relationships remain valid.os set to a platform the user isn't on — the task is rewritten to a passing no-op at build time
(moon task --json shows command: noop with cleared args/outputs).allowFailure: true — the failure is still recorded and displayed, but the pipeline continues and
moon exits successfully, so it's easy to miss.- A
condition check present v2.4+ — the task will skip whenever all conditions
pass. A task that "never runs" may have a condition that always passes.
- A
fingerprint check present v2.4+ — its script output is hashed, so volatile output
(timestamps, versions) causes cache misses on every run.
Step 2: Run with maximum verbosity
If the config looks right, run the task with debug logging to see what moon is actually doing under
the hood.
moon run <project>:<task> --log debug --force
MOON_DEBUG_PROCESS_ENV=true MOON_DEBUG_PROCESS_INPUT=true moon run <project>:<task> --log trace --force
What to look for in the logs:
- Toolchain resolution — is the right version of node/deno/bun/etc being used?
- Hash generation — what sources are being hashed?
- Affected status — is the task being skipped because it's "not affected"?
- Process execution — what command is actually being spawned?
Visualize the execution graph to spot dependency issues:
moon action-graph <project>:<task>
moon action-graph <project>:<task> --dot
For all graph commands and output formats, see references/environment-debug.md.
Step 3: Inspect cache state
If the task runs but produces wrong results, or runs when it shouldn't, or doesn't run when it
should, the cache is the likely culprit.
moon hash <hash>
moon hash <hash1> <hash2>
moon hash 0b55b234 2388552f
For cache file locations, hash interpretation, and the --force vs --cache off comparison, see
references/cache-issues.md.
Step 4: Diagnose the problem type
Use this table to jump to the right reference:
| Symptom | Likely cause | Quick check | Reference |
|---|
| Task doesn't exist | Inheritance not applied — check inheritedBy conditions in .moon/tasks/**/* against project's toolchains, stack, layer, tags via moon project <name> --json | moon task <target> --json | references/config-mistakes.md |
| "Nothing to do" | --affected + no changes, runInCI: false, or inheritedBy mismatch (global task not inherited) | Check flags, options.runInCI, and inheritedBy | references/decision-tree.md |
--affected misses changed files v2.4+ | Shallow git clone in CI — merge base can't be resolved, so diffs are inaccurate (moon now logs a warning) | Check clone depth; use full history or --filter=blob:none | references/decision-tree.md |
| Task fails: "requirement check failed" v2.4+ | A requirement check script exited non-zero, so the task refuses to run | moon task <target> --json — inspect checks | references/config-mistakes.md |
| Task skipped, not affected/CI-related v2.4+ | All condition checks passed, so the task was intentionally skipped | moon run <target> --log debug — look for "conditional checks have passed" | references/config-mistakes.md |
| Task errors on execution | Wrong command/script, bad toolchain | moon run <target> --log debug | references/config-mistakes.md |
| Stale cache (cached when it shouldn't be) | Inputs too narrow, missing env vars, or dep cacheStrategy: 'ignored' (the v2.3 default for output-less deps) |
Step 5: Validate the fix
After making changes, verify the fix actually worked:
moon run <project>:<task> --force
moon run <project>:<task> --cache off
moon task <project>:<task> --json
--force vs --cache off:
--force ignores existing cache but writes new cache after execution.--cache off disables caching entirely — no reads, no writes.
For all cache modes, see references/cache-issues.md.
Common mistakes at a glance
These are the issues that come up most often. For details and fixes, see
references/config-mistakes.md.
- Shell syntax in
command — pipes, &&, redirects require script; v2 rejects these as parse
errors.
- Missing
outputs on build tasks — cache can never hydrate artifacts.
- Overly broad
inputs — **/* invalidates cache on every change; be specific.
- Volatile outputs — timestamps or absolute paths in build artifacts cause permanent cache
misses.
- Persistent task in
deps — hard error; tasks named dev/start/serve auto-get server
preset.
--affected vs --force confusion — --affected restricts; --force bypasses cache
(they're opposites).allowFailure: true hiding errors — the failure is still recorded and displayed, but the
pipeline continues and moon exits successfully; check stderr at
.moon/cache/states/<project>/<task>/stderr.log.mutex contention — shared mutex serializes tasks; combined with deps can deadlock.runInCI: 'only' — task silently skips when run locally (most surprising variant).- Missing outputs flip dep
cacheStrategy v2.3+ — a dep without outputs now
defaults to cacheStrategy: 'ignored'. Downstream tasks stop invalidating on its changes; set
cacheStrategy: 'hash' explicitly to restore the pre-v2.3 default.
- MQL tag fields on task queries are version-dependent — in v2.3–v2.4,
taskTag= and tag=
(alias of projectTag) in moon query tasks --query silently matched nothing (this also broke
task tag glob targets like :#tag-*). Fixed in v2.5: taskTag matches the task's own tags, and
projectTag/tag match the parent project's tags. On older versions, filter task tags with the
--tags flag instead (moon query tasks --tags quality).
When to load references
Each reference file covers a specific problem domain in depth. Load them only when the diagnostic
flow points you there — don't load everything upfront.
| Reference | When to load |
|---|
references/decision-tree.md | When the symptom doesn't match the quick table above, or you need a systematic walk-through of all possibilities. |
references/cache-issues.md | When the problem is clearly cache-related: unexpected hits, unexpected misses, outputs not restoring. |
references/config-mistakes.md | When the task config is wrong: command vs script, inheritance bugs, presets, persistent tasks, affectedFiles, mutex, timeout, retries, runInCI variants, allowFailure, os. |
references/environment-debug.md | When you need to go deeper with env vars, log levels, trace profiles, or inspection tools. |
