Troubleshooting
Start with yidam doctor
It answers, in one screen, the questions that were previously spread across a stderr warning, a CI step and three reports. It writes nothing and does no network, so it is safe against a checkout you only mean to inspect — which the rest of the reports are not.
$ yidam doctor
yidam doctor — /home/you/my-domain
ok repository /home/you/my-domain
fail provenance .yidam.toml records no resolvable commit
→ mise run yidam-vendor-update
ok binary this repository pins no binary — nothing can be shadowed
skip commit .yidam.toml records no resolvable commit to compare against — see provenance
ok path this repository pins no binary — PATH order does not matter
warn prelude no .yidam/.vendor/prelude/ — this repository carries no vendored prelude
→ mise run yidam-vendor-update
warn index no /home/you/my-domain/.yidam/index
→ yidam index-build (needs the `index` feature)
ok computed this corpus computes nothing about itself, and declares no calculator
ok regen every REGEN block holds what its generator produces
warn routes `AGENTS.md` has no `yidam routes` block, so no re-vendor reaches its reading list
→ mise run yidam-vendor-update, then yidam migrate routes
warn scaffold no YIDAM region in `.github/workflows/ci.yml` or `.claude/CLAUDE.md`, so no re-vendor reaches the part that is yidam's
→ yidam migrate scaffold, then mise run yidam-vendor-update
ok ci runs yidam graph-check, yidam lint, yidam regen --check
ok catalog no TTL declared — 1 source(s) never expire. Set `[catalog] ttl_days` or declare `ttl_days:` on an entry.
fail corpora not installed: hydrology
→ mise run tonpa-install
ok corpus no corpus files yet
ok contract no classes yet
ok vault none declared
ok remote-index no remote index declared
ok policy 3 decision(s), all inherited
ok governance single-elector — no .yidam/sangha/electors.md
ok kuten none — the loop runs on the template's defaults
skip kuten-read no kuten is declared, so nothing carries one
ok build <version> (<commit>) with features: reports, export-graph, tonpa, serve-http, vault-s3, s3-vectors, catalog-fetch, pdf-text
2 failing check(s), 4 warning(s).
The version and commit are redacted; your own run prints them. Pinning a pair here would
only mean every release falsifies it. Each finding names its own remedy; a check with
nothing to do names none. It exits nonzero on what is wrong now; warnings — no index, an old pin — are reported and do not affect the
exit code unless you pass --strict, which is the reading a CI job wants.
| Check | The question |
|---|---|
repository | Am I in a derived repository? |
provenance | Does this repository record where it came from? |
binary | Is the running binary the one this repository pins? |
commit | Was the running binary built at the commit this repository pins? |
path | Is .yidam/bin ahead on PATH? |
prelude | How stale is the vendored prelude? |
index | Is the index built, and is it current? |
computed | What has this corpus computed about itself, and does it still stand? |
regen | Are the REGEN blocks current? |
routes | Does AGENTS.md carry the reading routes a re-vendor updates? |
scaffold | Do ci.yml and CLAUDE.md mark the part a re-vendor updates? |
ci | Does this repository's CI run a corpus gate? |
catalog | Have any source records aged out? |
corpora | Did the corpora this repository depends on arrive? |
corpus | Can every corpus file be read? |
contract | Has the ontology said what its classes require? |
vault | Can this repository reach its vaults, and where did each vault's credentials come from? |
remote-index | Is the declared remote vector index usable from here? |
policy | Do this repository's own rules compile, and which are its own? |
governance | Is this repository's governance mode carrying its own weight? |
kuten | Which kuten does this repository hold, and at what revision? |
kuten-read | Can anything in the loop read the kuten this repository holds? |
build | Which yidam is this, and what can it do? |
A skip is not a pass. Every check after repository skips when there is no repository to
check, so a screen of skips means the first line is the problem.
not bootstrapped yet
Error: not bootstrapped yet: /home/you/my-corpus was derived from yidam and has no
.yidam/ directory
`yidam clone` copied the template and pinned the commit it came from in .yidam.toml.
The ontology dialogue that writes .yidam/ has not run, so there is no corpus for this
command to read yet. Open this repository with an agent and start at BOOTSTRAP.md.
Nothing is wrong. clone hands you a pinned template; .yidam/ is written at genesis, which
is step 8 of the bootstrap dialogue. The step you have not done yet is
Quickstart §4.
yidam doctor reports this as a warn rather than a fail, and exits 0. A clone is not a red
build before anyone has had the chance to bootstrap it. --strict still refuses it, which is
the reading a CI job wants.
not a yidam repository
Error: not a yidam repository: /tmp/streamflow is not inside a git repository
yidam locates a repository with `git rev-parse --show-toplevel` and found none here. Run
this from inside a derived repository.
Inside a git repository that yidam never bootstrapped, the second line reads differently:
Error: not a yidam repository: /tmp/notes has no .yidam/ directory
This is a git repository, but not one yidam bootstrapped. Derive one with
`yidam clone <target>`, or overlay this one with `yidam overlay .`.
Every command that writes refuses this way, and every check does. A report does not: it
prints that it found nothing, which is a true answer. So export, bundle, schema,
graph-check, lint and doctor stop here, and graph or log tell you the corpus is
empty.
yidam finds the corpus by walking up to the git root. Two ways to hit this:
Nothing is a git repository. Reading an example has this shape — copy it out and initialise it, because running the binary inside the template's own directory finds yidam, which is not a corpus:
cp -R examples/streamflow /tmp/streamflow
cd /tmp/streamflow && git init -q && git add -A && git commit -qm 'genesis: streamflow'
yidam graph-check
The git root is not the corpus. A corpus nested inside a larger repository resolves to the
outer root. Pass --root <corpus>, which walks up to the nearest .yidam/ instead.
That reaches the corpus. One thing still will not work: export --format rdf refuses a
corpus that is not its own git repository. Its subjects are named with the corpus's first
commit. Git answers a nested directory with the enclosing repository. That repository's
genesis names a different corpus, and is shared by every corpus inside it. Copy the corpus out and give it a
repository, as above. Every other format works without an identity.
unrecognized subcommand
The command is real; your build does not carry it. Check what you have:
$ yidam --version
yidam <version> (<commit>) [reports tonpa]
That example build has no index, so yidam index-build is not there. The feature table is in
Installation; released binaries carry the default set.
This failure mode is why tonpa is a default feature despite costing an HTTP stack: it was the
one whose absence broke an instruction rather than removing a capability, and inside a script
with output redirected unrecognized subcommand is indistinguishable from success.
The gate fails and the finding is not mine
yidam lint asks did this change make the corpus less clean?, not is the corpus clean? If
you have inherited debt, adopt the ratchet rather than fixing everything first:
yidam lint --init-baseline # write .yidam/lint-baseline.yml if absent; safe to re-run
Existing findings become the baseline; new ones fail. After a genuine cleanup pass, re-bless — a baselined finding that is later repaired also fails the build, because the entry no longer describes reality and a stale ratchet has stopped ratcheting:
yidam lint --bless
yidam lint --explain prints each check's rationale beside its findings, which is usually
faster than guessing what a check is for.
A REGEN block is stale and CI is red
In a derived repository a stale <!-- REGEN: … --> block is a failing build. Refresh them all:
mise run regen # or: yidam regen
yidam regen --check # what CI runs — reports staleness, writes nothing
Careful: regen, status, open-questions and the other index commands rewrite files.
yidam --help-all marks each command that does with a *. Against a checkout you only
mean to read, yidam doctor is the one that is guaranteed not to touch anything.
this is a shallow clone, and a REGEN block cannot be generated from one. The block reports
the corpus genesis, which is the repository's first commit. A truncated history does not have it,
and git names the boundary commit a root instead. So the block would hold a date the clone
invented. Fetch the history and re-run:
git fetch --unshallow # locally
# in CI: actions/checkout with fetch-depth: 0
A REGEN block names a command no generator writes
1 REGEN block(s) name a command no generator writes. No generator writes that block, so
it holds whatever was last typed into it and yidam regen leaves it alone. A misspelling is
the usual cause — statsu for status.
The other cause is a generator whose command takes an argument, given none. count is the one:
<!-- REGEN: yidam count --> names no query, so no run can fill it. The block wanted is
<!-- REGEN: yidam count <query> -->, and the list below shows each generator in the form it is
written.
The check names the file, the command and the generators there are:
yidam regen --check
Correct the command, or delete the block. yidam regen cannot clear this one — there is
nothing to run.
Only commands beginning yidam are judged. A block your own tooling refreshes is left alone,
as is one a document shows inside a code fence.
The editor shows nothing, or disagrees with CI
Nothing at all. The extension activates only on a workspace containing .yidam.toml or
.yidam/. Opening the yidam template repository itself activates nothing — it has neither, by
design.
Nothing rendered, but it activated. It resolves a binary and never downloads or builds one.
Run yidam: Show binary and contract status to see which one answered. If the binary speaks a
report contract the extension does not understand, verdict features are disabled and the status
bar says so.
Verdicts disagree with CI. Almost always the wrong binary. The extension prefers the
repository's own build (.yidam/bin) over PATH precisely because a machine-wide binary is one
per machine while the pin is one per repository. yidam doctor answers this directly — the
binary and path checks exist for it.
Findings look too mild. Baseline membership outranks severity: inherited debt renders as a
Hint however severe the finding is. yidam.lint.showBaselined controls whether they appear at
all.
A finding that fails CI renders as a Warning. If it is not baselined, the extension
predates #655. Older builds read the check's declared severity rather than the finding's own.
missing-property raises a required: true omission past its check. Update the extension.
version GLIBC_2.39 not found on Linux
The release binary needs glibc 2.39 or newer, for its ONNX Runtime. Debian 12 and Ubuntu 22.04
are older. Install from source without vector-read instead. Installation
has the command. Retrieval is then keyword-only.
serve --mcp returns degraded
retrieve is doing keyword search rather than semantic search. It says so on every call
rather than returning keyword results as though they were embeddings. Every other MCP tool is
unaffected. degraded_reason names the cause. Usually there is no index yet (no_index).
Otherwise the binary lacks vector-read (no_vector_support). That is a binary from before it
joined the default set, or one built --no-default-features. An Intel Mac with no ONNX
Runtime is different: retrieve over an index is refused, not degraded. The error says to
brew install onnxruntime.
To get semantic retrieval you need a current binary and a built index:
yidam embed
yidam index-build
Connecting an agent covers what degraded and origin mean on the wire.
The index is stale
yidam index-status reports freshness against the corpus; doctor's index check summarises
it. Rebuild after corpus changes:
yidam embed && yidam index-build
If a provider is the question rather than the index — whether some other embedding runtime
reproduces this index — yidam index-verify --provider <cmd> checks it against the index's
reproducibility contract.
Catalog sources have aged out
catalog-expired names each one. TTLs are opt-in in both forms, and absent means nothing
expires: set [catalog] ttl_days in .yidam/config.toml for a corpus whose sources age alike,
or ttl_days: on the individual entry, which is the primary form because a gauge record and a
statute do not age at the same rate. See Configuration.
A corpus a dependency declares is not there
fail corpora not installed: hydrology
→ mise run tonpa-install
mise install fetches the corpora .yidam/tonpa.toml declares, through a postinstall hook.
A green mise install is not proof they arrived: mise logs a failing postinstall hook as a
warning and exits 0 anyway, so a corpus that could not be fetched leaves one line in a log that
scrolls past. This check is what still says so afterwards.
Run mise run tonpa-install on its own — invoked directly it returns a real exit code — and
read what it says about the dependency it could not get. A URL that has rotted is the common
cause; the remedy is a tonpa.toml edit, not a re-run.
Three other readings of the same check:
| Line | What it means |
|---|---|
does not match tonpa.lock: <name> | The bundle on disk is not the one this repository pinned. Re-run the install: it re-fetches at the locked hash. |
declared but never pinned: <name> | A warn. Normal between tonpa add and the first install — the dependency has no lock entry, so nothing can verify it. |
N path | Path dependencies, read from a sibling checkout. Nothing to fetch, and never graded. |
It answers offline. It compares what is unpacked under .yidam/tonpa/ against tonpa.lock,
which is the whole correctness story for a fetched corpus — so it works on a plane, and on a
binary built without the tonpa feature, which can read a corpus but not fetch one.
contract warns
Your ontology never answered one of two questions. Does an instance have to carry a property?
Is a class's edges: list closed? Until one class answers, the checks that read the answer
cannot gate.
Write required: on each property, true or false. Write edge_policy: on each class with
edges, exhaustive or characteristic. false and characteristic gate nothing, but they
answer the question. See The class contract in .yidam/.vendor/prelude/GRAPH.md.
The pin is old, or the prelude is stale
doctor's prelude check reports the age of the pinned commit — the commit's date, not the
date you last ran the vendor step. To adopt a newer template:
mise run yidam-vendor-update # re-vendor and re-pin to the newest cli/v* release
YIDAM_REF=v0.2.0 mise run yidam-vendor-update # target a tag or branch
This re-vendors .yidam/.vendor/prelude/ and rewrites .yidam.toml. It does not touch domain
content. Upgrading the binary is a separate act on a separate release train — see
Versioning and releases.
The update refuses because the pin is ahead
A pin taken with YIDAM_REF=HEAD usually sits ahead of the newest release. A plain
mise run yidam-vendor-update would then move it backwards, to an older prelude and binary. So
it refuses and changes nothing:
ERROR: this repository is pinned at <commit>, which <release> (<commit>) does not contain.
Re-vendoring to the newest release would move it backwards. Either:
YIDAM_REF=HEAD mise run yidam-vendor-update # stay on unreleased main (compiles)
YIDAM_REF=<release> mise run yidam-vendor-update # take the release, deliberately
Pick one. The first keeps you on unreleased main, and builds the binary from source. The second
moves back to the release because you named it. yidam-vendor-status says the same thing more
quietly: pinned ahead of <release> — nothing to adopt until a newer release.
commit fails
The running binary was built at a different commit than .yidam.toml's commit pins:
fail commit this binary was built at 1a2b3c4, but .yidam.toml pins 5d6e7f8
→ mise run yidam-build
This is the ordinary aftermath of a re-vendor. yidam-vendor-update rewrites the pin and leaves
.yidam/bin/yidam where it was. The prelude is then one commit ahead of the code reading it.
Run mise run yidam-build to rebuild the pin at the new commit.
The binary's stamp is a short hash, and the pin is a full one. They match when one is a prefix of the other. Two cases warn rather than fail:
- No
.yidam/bin/yidam. Whatever answered is ayidamfrom somewhere else. This repository never claimed to control it, so a mismatch is a warning. - The binary records no build commit. It cannot be matched to the pin either way.
yidam --versionshowsunknownwhere the commit should be.
A pin with no resolvable commit is provenance's finding. commit skips it rather than report
it twice.
vault names where credentials came from
doctor stays offline, so vault never asks a store anything. For each s3:// vault it says
which variables its credentials resolved from. Variables are named, never values:
ok vault 2 vaults configured (`default` AWS_ACCESS_KEY_ID, `sources` web identity via YIDAM_VAULT_SOURCES_ROLE_ARN); 3 artifact(s) cached
A file:// vault needs no credentials and is not listed. Read the list against what you meant.
A vault you meant to isolate should name its own YIDAM_VAULT_<NAME>_ variable.
It warns when:
- A vault has half a pair. One key without the other, or a role without its token file.
- A vault has both its own role and its own keys. The two name different principals, so it is refused. Unset one.
- A role's token file is missing. On EKS, check the service account's role annotation.
- Two vaults resolve to the same credentials. That is legal, but it is also what an unfinished isolation setup looks like.
The same rules hold for the remote index under YIDAM_INDEX_, which remote-index checks.
Configuration lists every variable.
Still stuck
yidam <command> --helpis generated from the same source as the behaviour, so it cannot disagree with the binary you have.- Open an issue with the output of
yidam doctorandyidam --version— between them they answer most of the first round of questions.