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.

# Show the fully resolved task config (with inheritance applied)
moon task <project>:<task>

# Machine-readable version for programmatic inspection
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.

# Debug-level logging with cache bypass
moon run <project>:<task> --log debug --force

# Deep debugging: reveal env vars and stdin passed to the process
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  # DOT format (useful for agents)

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.

# Inspect a hash manifest to see what inputs were hashed
moon hash <hash>

# Compare two hashes to see what changed between runs
moon hash <hash1> <hash2>

# Short-form hashes work too
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:

Step 5: Validate the fix

After making changes, verify the fix actually worked:

# Bypass cache to force a fresh run
moon run <project>:<task> --force

# Disable cache entirely (no reads OR writes)
moon run <project>:<task> --cache off

# Verify the resolved config reflects your changes
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).
• A checks script silently changes task behavior ^v2.4+ — a requirement failing aborts the task, a passing condition skips it, and a fingerprint mixes script output into the hash. Inspect checks in moon task <target> --json when a task fails, skips, or re-runs for no obvious reason.
• Shallow git clone breaks --affected ^v2.4+ — a shallow clone (depth 1) prevents moon from resolving the merge base, so affected detection is inaccurate or empty. Use a full clone, or a blobless partial clone (git clone --filter=blob:none).
• Experiments are now on by default ^v2.5+ — asyncGraphBuilding, asyncAffectedTracking, and nativeFileHashing default to enabled. When bisecting graph, affected, or hashing oddities, disable the relevant experiment (config or MOON_EXPERIMENT_*=false) and compare — but also check the user's shell/CI for MOON_EXPERIMENT_* or MOON_CACHE_* overrides that silently change behavior.
• Daemon archiving/hydration failures are invisible in the main process ^v2.5+ — with the daemon enabled, task outputs are archived and hydrated in the background, and failures only appear in moon daemon logs. To rule the daemon out, re-run with MOON_DAEMON=false.
• Workspace-level env is a new inheritance layer ^v2.5+ — .moon/tasks/**/* files can define env inherited by all matching projects. Project values win on conflict, unless workspace.mergeStrategies.env says otherwise (append, prepend, preserve, replace).

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.