TBDub Doctor

What it's for

TBDub is the awkward kind of ComfyUI pack: the node does almost nothing, and all the actual work happens in a separate Python environment you built by hand - a venv with CUDA torch, a pinned checkout of the upstream repo, and about 15 GB of weights. So when a dub fails, the error in the ComfyUI console is usually the last line of a stack trace from a different interpreter.

TBDub Doctor is the fix. It checks that entire runtime and tells you which of the five things is broken - the venv, the pinned upstream files, the weights, ffmpeg, or CUDA - without generating a single video and without loading a model.

Run it once after setup. Run it again the first time a job fails for no obvious reason.

What it actually checks

Two levels, one boolean. Light is the default and it's fast: the runtime's Python and package versions, the content hashes of 38 pinned upstream files (checked against the commit the pack expects), the official TBDub manifest validation, model file sizes, ffmpeg and ffprobe versions, whether JAX is the CPU build, whether torch can see CUDA (no CUDA context is created), and which attention backend upstream will pick. None of that needs a GPU.

deep is the real thing:

• SHA-256 of every model file, against pinned values - around 15 GB of disk reads, so it's disk-bound and takes a while.
• The safetensors headers compared against the model classes built on the meta device - keys, shapes, dtypes. This is what catches a truncated download or a wrong-revision file.
• A weights_only load of the prompt embedding.
• The MediaPipe face landmarker loaded exactly the way the runtime loads it.
• One real BF16 matmul plus an SDPA call on the GPU - the only check that proves your card can actually run this.

Every check reports pass/warn/fail with a detail line and a duration, and nothing aborts the run: a broken check and a healthy one look the same shape in the report.

Inputs and outputs

Only two fields, and one of them is the whole node.

• runtime_id - a dropdown of the runtimes registered in ComfyUI/user/tbdub.runtimes.json. If you haven't created that file, the dropdown reads (no runtime configured) and that is your problem.
• deep (default off) - the hash-everything mode described above.

The output is report, a JSON string. Doctor is also an output node, so it renders a short pass/fail list as a text preview in the UI while the full JSON goes on the wire. One detail worth knowing: the node re-runs on every queue (it reports a fresh timestamp instead of a cached value), so click Queue to re-check rather than expecting Cached.

Install

The node install is trivial and the runtime is not. There are no Python packages to install into ComfyUI's environment at all - the pack ships dependencies = [], which is why this one doesn't break your other nodes.

Drop it in via ComfyUI Manager (search TBDub, publisher hiroki-abe-58), or:

cd ComfyUI/custom_nodes
git clone https://github.com/hiroki-abe-58/ComfyUI-TBDub

Then the part that matters: build the runtime venv (Python 3.10, torch==2.9.0+cu128, the upstream checkout at commit 19e18e4, mediapipe==0.10.21, ffmpeg/ffprobe), download the weights, and register it:

cp ComfyUI/custom_nodes/ComfyUI-TBDub/examples/tbdub.runtimes.example.json \
   ComfyUI/user/tbdub.runtimes.json

Fill in your absolute paths, restart ComfyUI, add Doctor, run it light, then run it with deep.

Where people get burned

"(no runtime configured)" means the config file isn't where ComfyUI looks. It must be at the root of the ComfyUI user directory - not inside a per-user folder - or at whatever path COMFYUI_TBDUB_CONFIG points to.

"TBDub runtime config is invalid: …" - the schema is strict. Paths must be absolute and can't contain .., unknown keys are rejected outright, and the only env keys allowed are CUDA_VISIBLE_DEVICES and PYTORCH_CUDA_ALLOC_CONF. A typo'd key fails the whole file rather than being ignored.

"model files (sizes)" fails - the folder layout is the upstream --checkpoint-dir layout, subfolder included: config.json, null_prompt_emb.pt, tbdub_student.safetensors, Wan2.2_VAE.safetensors and face_landmarker.task at the top, with HuBERT's three files inside hubert-large-ll60k/. Point models_dir at the wrong level and every size check misses.

The JAX and OpenCV checks are the two MediaPipe traps. JAX must be the CPU build (jax/jaxlib 0.6.2) - MediaPipe needs it, TBDub itself never uses it on the GPU - and only one OpenCV package should be installed (opencv-contrib-python).

A checkout with Windows line endings is fine, by the way; the hashes are computed with CRLF normalised. So a "pinned file hashes" failure is real drift, not git being helpful.