Doctor and troubleshooting

Weld is designed so there are no dead ends: every error has a code, a likely cause and a fix, and one command checks everything.

weld doctor

weld doctor

Doctor runs without the hub or a database, so it works when the hub is the problem. It checks:

• Hub: URL, DNS, TCP, TLS, health, protocol and version compatibility, clock skew, your token.
• Tools: git, Git LFS, the git credential helper, missing prerequisites for your roles.
• Claude Code: installed, signed in, the Weld plugin, its hooks, the MCP server, telemetry settings.
• This machine: config file and permissions, the node service, ports, disk, Unreal and its MCP setup, Blender, GPU driver and GPU services.

Each failing check names its WELD-Exxxx code with the cause and fix.

Fixes

Command	What it does
weld doctor	Applies safe, reversible local fixes automatically (logged), for example refreshing a stale token
weld doctor --fix	Also offers fixes that touch other software, asking before each
weld doctor --yes	Applies every available fix without asking
weld doctor --no-fix	Report only
weld doctor --only hub	Only checks whose id starts with hub (repeatable, e.g. --only tools.git)
weld doctor --json	The report as JSON

Debug it with Claude

weld doctor --ai

Launches Claude Code with the weld-doctor skill, a redacted diagnostic bundle, the matching catalog entries and known issues, and Weld’s source for the exact version you’re running. It finds the root cause, fixes local problems (asking before it touches other software or data) and files a friction report for real Weld bugs.

Diagnostic bundles

A bundle holds the Weld version, OS, check results, the last 15 minutes of logs, redacted config and recent telemetry. It never includes secrets or prompt text, and it is only written when you ask:

weld doctor --bundle            # write one (default ~/.weld/doctor/)
weld doctor --share             # upload the redacted report so teammates can help
weld feedback "join hangs after the passkey step" --bundle ~/.weld/doctor/<bundle>

Shared reports from every node are visible to project members on the dashboard, so teammates can help each other.

Safe mode

weld --safe status

--safe (or WELD_SAFE=1) starts Weld with hooks, jobs and plugins disabled, to get past anything that breaks on startup.

Common problems

The hub is unreachable (WELD-E1101)

1. weld doctor --only hub names the failing layer: DNS, TLS, connect, HTTP or version.
2. Only your machine? Check your network and the URL in weld node status.
3. Everyone? The hub is down: tell whoever runs it. Keep working: git, Unreal and Claude Code don’t need the hub, hooks fail open and Work updates are queued until it’s back.

The node daemon isn’t running

weld status says node daemon not running. Run weld node run in the foreground to see why it stops (a port clash on 7421 shows here), then weld node install-service to run it at login again.

Token invalid or revoked (WELD-E2003)

weld auth refresh

If that fails, ask a project owner for a new invite, run weld node leave, then join again with the new join command.

Version mismatch (WELD-E1105, WELD-E1106, WELD-E1107)

weld update --yes installs the version your hub follows (and respects a freeze). The hub accepts the current and the previous protocol.

Missing tools: git, Claude Code, Blender, Unreal

weld setup              # shows each install command and asks first
weld node repair        # redo this machine's setup: prerequisites, git credentials, Claude settings, plugin and hooks

If an install fails (WELD-E9013), the message names the exact command and its log; run it yourself, then weld setup again. “Installed, but not found yet” (WELD-E9016): open a new terminal and run weld setup again.

Claude Code doesn’t show Weld context

The plugin may be missing or disabled (WELD-E7002). weld doctor checks the plugin, hooks and MCP server; weld node repair reinstalls them pinned to the current weld.

Jobs stay queued

• weld node caps on the machine that should run it: does it list the needed OS, GPU or tool?
• weld node role list: builds and the T1 gate may need a role (weld node role add build).
• weld jobs list --state queued: a job waiting for approval names who has to approve it (weld jobs approve <id> on that person’s machine).

Running out of disk

weld cache prune --dry-run shows what would go: Weld’s download and asset caches, logs older than 7 days, old crash dumps, and git lfs prune in linked repos.

Still stuck

Report it with weld feedback "<what happened>" (attach a bundle with --bundle), or let Claude do it: agents report friction with weld_report_friction. Reports feed Weld’s improvement loop. See When things break for a step-by-step version.