When things break

Weld is built so a problem never stops your work: hooks fail open, the node queues changes while the hub is away, and every error tells you what happened, why and what to do. When something does go wrong, work through these steps in order.

Read the error code.

Every Weld error has a stable code. In the terminal it looks like this:

✖ error WELD-E1101 Hub unreachable
  Can't reach the Weld hub at https://<your-hub>.
     why The hub server is down, restarting, or a firewall/proxy is blocking the
         connection. Your local work is safe and will be reconciled when the hub is back.
     fix Ask whoever hosts the hub, or check the watchdog email. […] Then re-run `weld doctor`.
    docs https://docs.weldhq.dev/reference/errors/#hub-unreachable

The same code shows in Claude Code (as a one-line notice), the web dashboard and the MCP tools. Look it up in the error code reference for the full cause and fix.

Run weld doctor.
Terminal window
```
weld doctor
```
It checks the hub connection (DNS, TLS, health, protocol, clock), your token, git and Git LFS, Claude Code and the Weld plugin, the node service, disk, Unreal, Blender and the GPU, and it works even when the hub is down. Safe, reversible fixes, such as refreshing a stale token, are applied automatically and logged. weld doctor --fix also offers fixes that touch other software, asking before each one.

Narrow it down with --only, for example weld doctor --only hub or --only tools.git.
Still red? Let Claude debug it.
Terminal window
```
weld doctor --ai
```
Claude Code starts with the weld-doctor skill, a redacted diagnostic bundle, the matching known issues and Weld’s source for your exact version. It finds the root cause, fixes local problems (asking before anything that touches other software or your data) and files a friction report if it’s a bug in Weld.
Ask a teammate.
Terminal window
```
weld doctor --share
```
Uploads the redacted report to the hub, where project members can see it on the dashboard and help.
Report it.

If Weld cost you time, tell us, even if you fixed it:
Terminal window
```
weld feedback "Join hung after the passkey step" --bundle ~/.weld/doctor/<bundle>
```
Claude does the same with weld_report_friction when Weld gets in its way. Reports feed the improvement loop that fixes Weld.

Quick fixes for common problems

Symptom	Try
`hub offline`, `WELD-E1101`	`weld doctor --only hub`. Only you? Check your network. Everyone? Tell the hub owner and keep working.
`node daemon not running`	`weld node run` in the foreground to see why, then `weld node install-service`.
`WELD-E2003` token invalid or revoked	`weld auth refresh`; if that fails, rejoin with a new invite (`weld node leave`, then the new join command).
Version mismatch (`WELD-E1105` and friends)	`weld update --yes`.
`git` or `claude` not found	`weld setup`, then open a new terminal (`WELD-E9016`).
No Weld note in Claude Code (`WELD-E7002`)	`weld node repair` reinstalls the plugin and hooks.
Jobs stay queued	`weld node caps`, `weld node role list`, and `weld jobs list --state queued` (someone may need to approve it).
Unreal MCP not answering	`weld game doctor --fix`, then reopen the editor.
A Weld update broke something	`weld update --rollback`.
Something breaks on startup	`weld --safe <command>` runs with hooks, jobs and plugins disabled.
Low disk	`weld cache prune --dry-run`, then without `--dry-run`.

More detail: Doctor and troubleshooting.

Last resort: rejoin

weld node leave        # undoes join's setup on this machine
weld node <join url>   # join again with a fresh invite from a project owner

weld node leave only removes this machine’s Weld config, key and cache. Your Work items and the game on the hub stay as they are, and so does your checkout.