Ynh Troubleshoot

Troubleshoot a broken setup

The commands to diagnose almost anything here already exist. What is missing is knowing which one to reach for, so this skill is a routing table, not a tutorial.

The rule that saves the most time

Establish where the truth diverges before changing anything. There are four places a harness can be wrong, and the fix is different in each:

the manifest  →  what composition resolved  →  what the vendor received  →  what the vendor did
   ynd validate      ynd compose                  ynd preview                 vendor's own logs

Walk it left to right and stop at the first surprise. Most sessions that go wrong start by editing the manifest when the manifest was fine.

Start here, always

ynh doctor

It checks the setup as a whole — vendor availability, installed-harness integrity, manifest validity of what is installed, symlink health, launcher and PATH, and anything sitting in quarantine — and reports findings with the command that fixes each. It is read-only: it will tell you what is wrong and never change it.

If ynh doctor is clean and the problem persists, the fault is in the harness content rather than the installation, so go to the symptom table.

Symptom → command

When ynh check gates

ynh check exits 0 pass, 1 a blocking sensor failed, 2 the gate could not run. Exit 2 is not a failing check — it is a check that could not happen, and the two get confused constantly.

ynh check <name> --format json     # the full result, including per-sensor status
ynh check <name> --only <sensor>   # narrow to one
ynh sensors show <name> <sensor>   # what that sensor actually resolves to

In JSON these are two fields, not one. The text output merges them into a single column, which misleads when you go looking for "status": "stale" and find "status": "fail":

{ "name": "e2e-status", "status": "fail", "freshness": "absent" }

So a files sensor that fails reports status: fail plus a freshness saying why. If freshness is set, the content was never the problem.

Three specific traps:

• absent on a sensor that used to pass — the artifact is not being produced any more. The sensor is right; the producer broke.
• stale on every files sensor after one commit — observes is not declared, so the whole tree counts. One line of config fixes it.
• A blocking sensor that never fails — it may have stopped observing. ynh check <name> --calibrate runs each against its reference fixture. uncalibrated means nobody has proved it bites.

Note ynh check takes an installed id, not a path. ynh check ./my-harness fails, including the ./<path> form the error message suggests. Install first, then --cwd to point at the tree.

Reading the four layers

When the symptom table does not settle it, walk the pipeline explicitly and show the user each step:

ynd validate <dir>                     # 1. is the manifest and are the artifacts well-formed?
ynd compose <dir> --format text        # 2. what resolved, and from where?
ynd preview <dir> -v <vendor>          # 3. exactly what will the vendor receive?
ynd diff <dir> claude cursor           # 3b. is this vendor-specific?

The first one that surprises them is where the fault is. Say which layer you are in as you go — "the manifest is fine, the composition is fine, the preview is missing your rules" is a diagnosis; "it doesn't work" is not.

How to answer

• Run the command; do not describe it. Paste the real output.
• Say which layer the fault is in before proposing a fix.
• One change at a time, re-running the command that showed the problem. A fix that is not verified by the same command that found the fault is a guess.
• If you cannot reproduce it, say so and ask for the output of ynh doctor and the relevant ynd preview rather than speculating.