Skip to content

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.

CheckThe question
repositoryAm I in a derived repository?
provenanceDoes this repository record where it came from?
binaryIs the running binary the one this repository pins?
commitWas the running binary built at the commit this repository pins?
pathIs .yidam/bin ahead on PATH?
preludeHow stale is the vendored prelude?
indexIs the index built, and is it current?
computedWhat has this corpus computed about itself, and does it still stand?
regenAre the REGEN blocks current?
routesDoes AGENTS.md carry the reading routes a re-vendor updates?
scaffoldDo ci.yml and CLAUDE.md mark the part a re-vendor updates?
ciDoes this repository's CI run a corpus gate?
catalogHave any source records aged out?
corporaDid the corpora this repository depends on arrive?
corpusCan every corpus file be read?
contractHas the ontology said what its classes require?
vaultCan this repository reach its vaults, and where did each vault's credentials come from?
remote-indexIs the declared remote vector index usable from here?
policyDo this repository's own rules compile, and which are its own?
governanceIs this repository's governance mode carrying its own weight?
kutenWhich kuten does this repository hold, and at what revision?
kuten-readCan anything in the loop read the kuten this repository holds?
buildWhich 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:

LineWhat 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 pathPath 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 a yidam from 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 --version shows unknown where 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> --help is 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 doctor and yidam --version — between them they answer most of the first round of questions.