td-atlas RU·EN Try it

Troubleshooting

Перевод английской документации от 15.09·English

Run td-atlas doctor first for anything that looks like a setup problem. It walks the whole chain, from the environment through TouchDesigner, the index, the index build, the probe, the bridge and the MCP server. Every link that is not ok comes with the command that repairs it, and a broken link makes doctor exit non-zero.

Symptom What it is What to run
Symptom doctor says bridge : absent What it is no TouchDesigner has registered a bridge, and nothing is listening on the port What to run open the project and paste the td-atlas install bootstrap line into the textport
Symptom a live tool refuses with "nothing answered on the bridge port" What it is TouchDesigner is not running, or is running without the bridge What to run td-atlas doctor, then the bootstrap line
Symptom "The running bridge reports protocol N, below the minimum 7 this client supports" — and, from an MCP tool, that line plus the hint "the bridge and this host speak different protocol versions" What it is the staged bridge is older (or newer) than this checkout. The oldest bridge accepted is protocol 7, and anything older is refused at connect What to run td-atlas reload — it is the one command that talks to a bridge the version check would otherwise reject
Symptom a call comes back UnknownMethod What it is the same thing from the other side. The bridge was staged from an older package, so it has no such method What to run td-atlas reload, then repeat the call
Symptom "the bridge rejected the token this host sent" What it is the bridge's token and ~/.td-atlas/config.json disagree What to run td-atlas doctor compares them; td-atlas install re-stages against the current one
Symptom "something answered on that port but not with a bridge reply" What it is another program holds the port, or the Web Server DAT is misconfigured What to run td-atlas doctor, then td-atlas install
Symptom a call times out What it is every request runs on TouchDesigner's main thread during a cook, so a long script blocks it What to run wait, then retry in smaller pieces, a short td_exec at a time
Symptom "this host has no atom index yet" What it is nothing was built What to run td-atlas build, then td-atlas probe with TouchDesigner open
Symptom "the index names a file that is not on disk" What it is TouchDesigner was moved, updated or reinstalled since the index was built What to run td-atlas build, then td-atlas probe
Symptom doctor says index build disagrees What it is the index was built from a different TouchDesigner than the one installed now, and the tools answer with that other build's values What to run td-atlas build
Symptom a network reply ends TRUNCATED:, or a line reads ... N more child(ren) not listed What it is the network is larger than one reply carries. The node budget or the per-component child cap stopped it, and the reply names where What to run ask again with a narrower path
Symptom a line reads ... N direct child(ren), not walked at depth D What it is there are N more operators directly under that node, and the depth you asked for stops above them. N counts direct children, so whatever hangs below them is on top of it What to run ask again with a larger depth, or path at that node
Symptom td_errors says "the walk stopped after N operator(s) at and under path", or td_health says "only N operator(s) at and under path were sampled" What it is the walk hit its node budget. A clean answer covers the part that was walked, and the remainder each names is a floor What to run run it again on a subtree, with path
Symptom td_errors reports nothing about a component you just built What it is its path defaults to the project. Asking for / makes it worse: the walk is breadth-first and bounded, and TouchDesigner's own /ui and /sys swallow the budget before anything of yours is reached What to run name the component in path
Symptom td_health reports script errors it could not read What it is the read failed on this build, so treat that area as unchecked What to run the reply names the reason
Symptom a write refuses because the output already exists What it is toecollapse renames what it finds to <name>.bkp1, and nothing is written over What to run choose a path that does not exist
Symptom ~/.td-atlas/cache has grown What it is every offline read unpacks a copy there. The cache is capped and evicted least-recently-used, and an old one stays until you empty it What to run td-atlas doctor says how many expansions it holds, td-atlas doctor --clear-cache empties it
Symptom the MCP client cannot start the server What it is it is launching an interpreter that has no td_atlas installed What to run td-atlas install prints the exact claude mcp add line, absolute interpreter path and all; doctor's mcp server link verifies it

td-atlas log --failures shows what the bridge refused, with timestamps, after the fact. td_log is the same for an agent.