Diagnose and fix moon tasks that are broken, misconfigured, or behaving unexpectedly. Use this skill when a moon task is failing, not running, skipped, hanging, producing stale or wrong output, cached when it shouldn't be, re-running every time when it should be cached, or when outputs are empty or

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](https://moonrepo.dev/docs). 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. 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 <sup v2.4+</sup — 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 <sup v2.3+</sup — 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 <sup v2.4+</sup — the task will skip whenever all conditions pass. A task that "never runs" may have a condition that always passes. A fingerprint check present <sup v2.4+</sup — 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. 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: 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. 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 <sup v2.4+</sup 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" <sup v2.4+</sup 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 <sup v2.4+</sup 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) moon hash <hash references/cache issues.md Cache miss (re runs every time) Inputs too broad, volatile outputs, or dep cacheStrategy: 'hash' propagating upstream churn moon hash <h1 <h2 references/cache issues.md Cache miss from a fingerprint check <sup v2.4+</sup A fingerprint check's script output is volatile (timestamps, PIDs), changing the hash every run moon hash <h1 <h2 — look for the check hash references/cache issues.md Outputs not restored after cache hit outputs misconfigured; or <sup v2.5+</sup a daemon side archive/hydrate failure — swallowed by the main process, logged only by the daemon (a failed hydrate becomes a silent cache miss) Check .moon/cache/outputs/ ; moon daemon logs references/cache issues.md Env var has unexpected value <sup v2.5+</sup Workspace level env in .moon/tasks/ / merged in, or workspace.mergeStrategies.env changed the merge behavior moon task <target json — inspect env references/config mistakes.md Cache behaves differently across git worktrees <sup v2.5+</sup cache.unstable sharedWorktreeCache shares blobs/manifests via the base checkout's .moon/cache Check the setting and MOON CACHE SHARED WORKTREE CACHE references/cache issues.md New dependency cycle error after upgrading to v2.5 Async graph building (now default) validates cycles strictly, per dependency scope partition Set experiments.asyncGraphBuilding: false to confirm references/decision tree.md Build re runs on every upstream input change <sup v2.3+</sup Dep using default cacheStrategy: 'hash' instead of 'outputs' moon task <target json — inspect dep entries references/cache issues.md Task not matched by tag target <sup v2.3+</sup Missing tags on the task, or mergeTags dropped them during inheritance moon task <target json — check tags references/config mistakes.md Task hangs / pipeline stuck Persistent task in deps chain (hard error in v2) moon action graph <target references/config mistakes.md Task is slow Dep chain bottleneck, no parallelism moon action graph <target

debug-task