Every user-facing error in Weld has a stable code, WELD-Exxxx. The CLI, the web dashboard, the MCP tools Claude uses and the hub API all show the same three things: what happened , why (the most likely cause) and the fix . This page lists all 213 codes and is generated from the same catalog the software uses.
Run weld doctor. It checks this machine, names the code, applies safe fixes itself and asks before anything that touches other software. weld doctor --ai hands what is left to Claude Code with a diagnostic bundle. See Doctor and troubleshooting .
Codes are never reused or renumbered. In a message, {name} stands for a detail filled in at the time (a path, a version, a node name). Severity is info, warning, error or fatal. An auto-fix means weld doctor can repair it for you.
Message: {detail}Why: The request parameters are invalid.Fix: Check the arguments, e.g. trace ids are 32 hex characters.Severity: error · HTTP: 400
Message: telemetry store errorWhy: The hub’s telemetry.db failed.Fix: Check hub disk space and telemetry.db permissions; see hub logs.Severity: error
Message: trace {trace} not foundWhy: No spans or logs with this trace id are stored (older than retention or not forwarded yet).Fix: Check the id, or search logs with weld ops logs.Severity: error · HTTP: 404
Message: {detail}Why: Unexpected server-side failure.Fix: Retry; if it repeats run weld doctor --share and check the hub logs.Severity: error
Message: no or invalid credentialsWhy: The request had no valid token or session.Fix: Run weld doctor (it can refresh the device token) or re-join with weld node <join-url>.Severity: error · HTTP: 401
Message: coordination database errorWhy: The hub’s coord.db failed.Fix: Check hub disk space and logs (journalctl -u weld-hub).Severity: error
Message: forbidden: {detail}Why: Authenticated, but not allowed (not a project member, not the owner, …).Fix: Ask a project owner for access.Severity: error · HTTP: 403
Message: {what} was not found.Why: It does not exist or is not visible to you.Fix: Check the id and your current project (weld status).Severity: error · HTTP: 404
Message: {detail}Why: The request conflicts with current state (duplicate, already taken, …).Fix: Refresh and retry.Severity: error · HTTP: 409
Message: The request was rejected: {detail}.Why: Malformed or invalid request body, query or path; often a version mismatch.Fix: Run weld update; if it persists run weld doctor --share.Severity: error · HTTP: 400
Message: node and hub protocol versions are incompatibleWhy: The hub accepts its current and previous protocol only.Fix: Run weld update on the node (or update the hub).Severity: error · HTTP: 426
Message: the secrets key is missing, unreadable or does not decryptWhy: The hub’s age key file is missing or wrong.Fix: Restore the key file from the offline recovery copy and restart the hub.Severity: error
Message: {detail}Why: The job is not in a state that allows this operation.Fix: Refresh the job (weld jobs list) and retry.Severity: error · HTTP: 409
Message: this node is not assigned to the jobWhy: Only the node a job is assigned to may report on it.Fix: Nothing to do; the assigned node will report.Severity: error · HTTP: 403
Message: dev: tokens require a hub started with –devWhy: A dev: token was used against a production hub.Fix: Use a real device token (weld node <join-url>).Severity: error · HTTP: 401
Message: {detail}Why: Malformed WebSocket message or not allowed for this client.Fix: Run weld update; if it persists this is a bug.Severity: error · HTTP: 400
Message: {detail}Why: The job did not declare the secret it asked to lease.Fix: Declare the secret in the job definition.Severity: error · HTTP: 403
Message: Can’t reach the Weld hub at {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. If you run the hub, check it on that machine with weld hub status (start it with weld hub start; on a provisioned server systemctl status weld-hub). Then re-run weld doctor.Severity: error · HTTP: 502
Message: The hub hostname {host} could not be resolved.Why: The DNS record is missing or still propagating, the domain is mistyped in your config, or this machine has no working DNS.Fix: Check hub_url in your Weld config. Try nslookup {host}. If you just provisioned the hub, wait a few minutes for DNS to propagate.Severity: error
Message: A secure connection to {hub} could not be established.Why: The hub’s certificate is invalid, expired or for another name, the system clock is far off, or a corporate proxy intercepts TLS.Fix: Run weld doctor to check clock skew. Open {hub}/health in a browser to inspect the certificate. If you use a Cloudflare Tunnel, check that it is connected.Severity: error
Message: The hub at {hub} answered /health with {status}.Why: The hub process is up but one of its subsystems (database, disk, background tasks) is failing.Fix: Run weld ops health for details, or check the hub logs: weld hub logs on the hub machine (on a provisioned server journalctl -u weld-hub -n 200).Severity: error · HTTP: 503
Message: This node speaks protocol {node_protocol}, but the hub requires protocol {hub_protocol} or newer.Why: The hub was updated and accepts only the current and previous protocol versions.Fix: Run weld update to install the latest release for your channel.Severity: error · Auto-fix: weld doctor (self-update) · HTTP: 426
Message: The hub speaks protocol {hub_protocol}, which is older than this node’s minimum ({node_protocol}).Why: This node was updated ahead of the hub (for example from the canary channel).Fix: Ask the hub owner to update the hub, or roll this node back with weld update --rollback.Severity: error
Message: This node runs weld {node_version} but the hub runs {hub_version}.Why: Updates roll out at idle time, so short version differences are normal. Long-lived skew can hide bugs.Fix: Run weld update when convenient.Severity: warning
Message: The hub is rate limiting requests from this node.Why: A loop or a misbehaving agent is sending too many requests.Fix: Wait a minute and retry. If it persists, run weld doctor --share so the hub owner can see which client is looping.Severity: warning · HTTP: 429
Message: The hub failed while handling {operation}.Why: A bug or an unexpected condition on the hub. It has been logged with a fingerprint on the hub.Fix: Retry the operation. If it keeps failing, run weld doctor --share and mention the time it happened.Severity: error
Message: The live connection to the hub dropped; reconnecting.Why: Network change, laptop sleep, or a hub restart. Events are replayed on reconnect so nothing is lost.Fix: Nothing to do unless this persists for minutes; then run weld doctor.Severity: warning
Message: “{hub}” is not a valid hub URL.Why: The URL is missing the scheme (https://) or contains a typo.Fix: Use the join URL you were given, e.g. weld node https://hub.example.com/join/<invite>.Severity: error · HTTP: 400
Message: {hub} responded, but not like a Weld hub.Why: The URL points at another web server, a captive portal, or a proxy error page.Fix: Double-check the hub URL. Open {hub}/health in a browser; it should show JSON with a protocol field.Severity: error
Message: The hub could not read or write its database.Why: The hub disk is full, the database file is locked or corrupted, or permissions changed.Fix: On the hub run df -h /var/lib/weld and journalctl -u weld-hub. Restore from backup with weld restore if the database is corrupted.Severity: fatal · HTTP: 503
Message: The last successful backup to R2 was {age} ago.Why: Litestream cannot reach R2 or its credentials expired.Fix: On the hub run systemctl status litestream and check the R2 token in /etc/weld/hub.env.Severity: warning
Message: not signed inWhy: The request had no session cookie and no bearer token.Fix: Sign in in the browser, or run weld login / pass Authorization: Bearer <token>.Severity: error · HTTP: 401
Message: session expiredWhy: Your session was idle for more than 30 days or you logged out.Fix: Sign in again.Severity: error · HTTP: 401
Message: token is invalid or revokedWhy: The bearer token is unknown, malformed or has been revoked.Fix: Create a new token (weld login) or re-join the node with a fresh invite.Severity: error · HTTP: 401
Message: missing or wrong CSRF tokenWhy: Cookie-authenticated requests that change state must send the X-Weld-CSRF header with the value of the weld_csrf cookie.Fix: Reload the page. API clients should use a bearer token instead of cookies.Severity: error · HTTP: 403
Message: cross-origin request rejectedWhy: The request’s Origin header does not match the hub’s public URL.Fix: Use the hub from its configured public URL (--public-url).Severity: error · HTTP: 403
Message: No device token is configured for {hub}.Why: This node never joined, or the token was removed from the config.Fix: Run weld node <join-url>.Severity: error · HTTP: 401
Message: The hub rejected this node’s device token as expired.Why: Device tokens expire after a period of inactivity.Fix: Run weld doctor --fix to refresh it, or re-join with weld node <join-url>.Severity: error · Auto-fix: weld doctor (refresh-token) · HTTP: 401
Message: code is invalid or expiredWhy: The code is wrong, was already used, or is older than 10 minutes.Fix: Request a new code and enter the latest one.Severity: error · HTTP: 401
Message: too many attemptsWhy: Too many sign-in attempts. Try again in about {retry_after_secs} seconds.Fix: Wait a few minutes before retrying.Severity: warning · HTTP: 429
Message: forbidden: {detail}Why: You are not allowed to {detail}.Fix: Ask a project owner to grant you access.Severity: error · HTTP: 403
Message: not found: {detail}Why: The {detail} does not exist or you cannot see it.Fix: Check the id and your project membership.Severity: error · HTTP: 404
Message: invite is invalid, expired or used upWhy: The invite code is unknown, expired, revoked or has no uses left.Fix: Ask a project owner for a new invite link.Severity: error · HTTP: 410
Message: an account with this email already existsWhy: This open invite cannot claim an email that already has an account.Fix: Sign in first (browser or weld login) and open the invite again, or ask for an invite addressed to your email.Severity: error · HTTP: 409
Message: no invite for {detail} on this hubWhy: This hub has no account and no pending invite for that address, and it does not allow self sign-up.Fix: Ask a project owner to run weld invite <your email>, then run weld node again.Severity: error · HTTP: 404
Message: this machine’s sign-in request expired or was already usedWhy: Sign-in requests from weld node last 10 minutes and work once.Fix: Run weld node again and approve the new request in the browser.Severity: error · HTTP: 410
Message: adding this machine was denied in the browserWhy: Someone signed in to the hub chose Deny for this machine’s request.Fix: If that was a mistake, run weld node again and choose Approve.Severity: error · HTTP: 403
Message: bad request: {detail}Why: {detail}Fix: Fix the request and retry.Severity: error · HTTP: 400
Message: conflict: {detail}Why: {detail}Fix: Fix the request and retry.Severity: error · HTTP: 409
Message: passkey verification failed: {detail}Why: The passkey ceremony failed: {detail}.Fix: Retry; if it keeps failing, sign in with an email code instead.Severity: error · HTTP: 400
Message: email delivery failed: {detail}Why: The email provider rejected or failed the request: {detail}.Fix: Check WELD_RESEND_API_KEY and the sender address, then retry.Severity: error · HTTP: 502
Message: configuration error: {detail}Why: {detail}Fix: Fix the hub configuration and restart the hub.Severity: error
Message: internal error: {detail}Why: A database, migration or internal error in hub auth.Fix: Check the hub logs, disk space and that coord.db is not from a newer hub version; this is a bug if it repeats.Severity: error
Message: No Weld config was found at {path}.Why: This machine has not joined a hub yet, or the config directory was moved.Fix: Run weld node <join-url> with the join URL from your hub invite.Severity: error
Message: The config at {path} could not be read: {detail}.Why: The file was edited by hand and has a syntax error, or it was written by a much newer weld.Fix: Fix the line mentioned above, or move the file aside and re-run weld node <join-url>.Severity: error
Message: {path} contains a device token but is readable by other users (mode {mode}).Why: The file was copied or created with a permissive umask.Fix: Run chmod 600 {path} (weld doctor can do this for you).Severity: warning · Auto-fix: weld doctor (fix-config-permissions)
Message: Port {port} is already in use by another program.Why: Another weld node is running, or an unrelated program uses the port.Fix: Stop the other program, or find it with lsof -i :{port} (macOS/Linux) or netstat -ano | findstr {port} (Windows).Severity: error
Message: The weld node service is installed but not running.Why: It crashed, was stopped, or failed to start after an update.Fix: Restart it with weld doctor --fix or start it manually; check crash reports with weld doctor.Severity: error · Auto-fix: weld doctor (restart-service)
Message: The hub does not know node {node}.Why: The node was removed from the hub, or the hub was restored from an older backup.Fix: Re-join with weld node <join-url>.Severity: error · HTTP: 404
Message: Work item {work} does not exist.Why: It was merged and archived, or the id is mistyped.Fix: List current work with weld work list.Severity: error · HTTP: 404
Message: Your work overlaps with {other} ({scope}).Why: Another person’s active Work item touches the same feature scope.Fix: Choose coordinate, proceed or pivot when asked. You will only be asked once.Severity: warning · HTTP: 409
Message: {path} could not be parsed: {detail}.Why: A glob or scope name is malformed.Fix: Fix the entry; scope kinds are system, ui-screen, cpp-module, asset, map-cell, doc and file.Severity: error
Message: The hub is unreachable; {count} change(s) are queued locally.Why: The node is offline or the hub is down.Fix: Nothing to do. Queued work is reconciled automatically when the hub is reachable.Severity: info
Message: weld crashed during startup at {time}; a crash report was saved to {path}.Why: A bug, a corrupted local cache, or a plugin/hook that fails on load.Fix: Start with weld --safe (hooks, jobs and plugins off), then run weld doctor --ai.Severity: error
Message: The weld {hook} hook failed and was skipped.Why: The node is not running or hit an internal error. Hooks fail open, so your Claude session continues.Fix: Run weld doctor.Severity: warning
Message: The local weld MCP server at {url} is not responding.Why: The node daemon is not running or crashed.Fix: Run weld doctor --fix to restart the node.Severity: error · Auto-fix: weld doctor (restart-service)
Message: The local cache at {path} is unreadable.Why: A crash or full disk interrupted a write.Fix: Delete the cache file; it is rebuilt from the hub on the next connect.Severity: warning
Message: {detail}Why: The command needs a project and none was given or linked for this directory.Fix: Run inside a linked repo (weld node link), pass --project <name|id>, or create one with weld project create <name>.Severity: error
Message: {detail}Why: No member of the project matches that email, name or user id (or several do).Fix: List members with weld project members, or invite them with weld invite <email>.Severity: error · HTTP: 400
Message: {detail}Why: The OS service manager (launchd, systemd –user or Task Scheduler) rejected the unit.Fix: Run weld node install-service again and read the error; you can always run weld node run in a terminal instead.Severity: error
Message: The node daemon runs weld {daemon} but this weld is {cli}.Why: weld was updated while the node was running, and the node was not restarted (e.g. it runs in another terminal).Fix: Run weld doctor --fix to restart the node service, or stop weld node run (Ctrl-C) and start it again.Severity: warning · Auto-fix: weld doctor (restart-service)
Message: {detail}Why: The command line does not match what weld accepts (unknown command, missing or unexpected argument).Fix: See weld --help or weld <command> --help for the exact usage.Severity: error
Message: {detail}Why: An unexpected error in the hub’s git hosting.Fix: Check the hub log (weld doctor); retry the operation.Severity: error
Message: authentication required for this git repositoryWhy: git sent no credentials or the device token was rejected.Fix: Run weld git setup in the repo so git uses weld’s credential helper, or use your device token as the HTTP password.Severity: error · HTTP: 401
Message: you don’t have access to this repositoryWhy: Your account is not a member of the project or lacks write access.Fix: Ask a project owner to invite you (or grant write access).Severity: error · HTTP: 403
Message: invalid {what} name {name}Why: Names must be 1-100 chars of letters, digits, ‘.’, ‘_’ or ‘-’ and start with a letter or digit.Fix: Rename it (e.g. my-game).Severity: error · HTTP: 400
Message: repository {project}/{repo} does not existWhy: Nobody has created or pushed it yet.Fix: Push to it to create it, or create it with POST /api/v1/projects/<p>/repos.Severity: error · HTTP: 404
Message: unknown git endpoint /git/{path}Why: Only smart HTTP and the Git LFS batch API are served.Fix: Use a URL like https://<hub>/git/<project>/<repo>.git.Severity: error · HTTP: 404
Message: {detail}Why: The LFS client sent a body the hub could not read or parse.Fix: Update git-lfs to 3.x and retry.Severity: error · HTTP: 400
Message: {detail}Why: The object store behind LFS failed or is misconfigured.Fix: Check hub disk space and storage settings (weld doctor).Severity: error · HTTP: 502
Message: this hub does not serve LFS objects directlyWhy: LFS objects are stored in object storage behind presigned URLs.Fix: Use the hrefs returned by the LFS batch API.Severity: error · HTTP: 404
Message: {detail}Why: The ref or path does not exist in this repo.Fix: Check the branch name and path (list branches with .../branches).Severity: error · HTTP: 404
Message: {detail}Why: Invalid ref or path parameter.Fix: Use a branch name, tag or commit id for ref, and a repo-relative path.Severity: error · HTTP: 400
Message: {detail}Why: Reading this commit or diff took longer than the hub allows (very large change or a busy hub).Fix: Retry; for huge changes open single files with “load full diff” or inspect the commit locally with git show.Severity: error · HTTP: 504
Message: could not run git ({bin}): {detail}Why: git is not installed or not on PATH.Fix: Install git >= 2.38 (macOS: brew install git; Windows: git-scm.com) and rerun.Severity: error
Message: git {cmd} timed outWhy: The network or hub is slow/unreachable, or a git lock is held.Fix: Check weld doctor, then retry.Severity: error
Message: git {cmd} failed: {detail}Why: git reported an error (see message).Fix: Read the git error; for authentication failures run weld git setup ..Severity: error
Message: {path} is not inside a git repositoryWhy: The directory has no .git.Fix: Run the command inside your game repo, or clone it first.Severity: error
Message: git {version} is too old; weld needs git >= 2.38 (merge-tree –write-tree)Why: An old system git is first on PATH.Fix: Install git >= 2.38 and make sure it comes first on PATH.Severity: error
Message: unexpected git output: {detail}Why: An unsupported git version or locale.Fix: Update git; run with LC_ALL=C if you use a non-English locale.Severity: error
Message: I/O error: {detail}Why: Filesystem permissions or disk space.Fix: Check permissions and free space (weld doctor).Severity: error
Message: {detail}Why: Invalid input.Fix: Fix the input and retry.Severity: error
Message: git was not found on PATH.Why: git is not installed, or it is installed somewhere not on PATH.Fix: Run weld setup (installs it after asking: winget on Windows, Homebrew on macOS, apt/dnf on Linux). Manually: macOS xcode-select --install; Windows winget install --id Git.Git -e; Linux your package manager.Severity: error · Auto-fix: weld doctor (install-prereqs)
Message: git {version} is installed but Weld needs {required} or newer.Why: Weld uses git merge-tree --write-tree, added in git 2.38.Fix: Run weld setup to update it (macOS brew install git, Windows winget upgrade --id Git.Git -e).Severity: error · Auto-fix: weld doctor (install-prereqs)
Message: git-lfs was not found.Why: Git LFS is a separate install from git on most systems.Fix: Run weld setup (installs it after asking). Manually: macOS brew install git-lfs, Windows it ships with Git for Windows, Linux apt install git-lfs; then git lfs install.Severity: error · Auto-fix: weld doctor (install-prereqs)
Message: git-lfs {version} is installed but Weld needs {required} or newer.Why: Older git-lfs versions lack features the hub’s batch API relies on.Fix: Update git-lfs with your package manager.Severity: warning
Message: git-lfs is installed but its git hooks are not set up for this user.Why: git lfs install was never run on this machine.Fix: Run git lfs install.Severity: warning · Auto-fix: weld doctor (git-lfs-install)
Message: git is not configured to use weld for {hub}.Why: The credential helper was removed or weld node setup did not finish.Fix: Run weld doctor --fix to register it again.Severity: warning · Auto-fix: weld doctor (register-credential-helper)
Message: The hub rejected the push to {ref}.Why: The branch moved on the hub, or protected refs can only be updated by the merge queue.Fix: Pull and retry, or submit through the merge queue with weld merge.Severity: error · HTTP: 409
Message: {a} and {b} conflict in {files}.Why: Two branches changed the same lines or the same binary asset.Fix: Resolve it on your branch and re-queue with weld merge <work> (a node with the merge role proposes a resolution automatically: weld node role add merge), or pick a side for binary assets.Severity: warning · HTTP: 409
Message: Pushing the WIP ref for {work} failed.Why: The hub is unreachable or git authentication failed.Fix: This retries automatically. If it keeps failing run weld doctor.Severity: warning
Message: Transferring LFS object {oid} failed: {detail}.Why: The presigned storage URL expired, the network dropped, or the object store is unavailable.Fix: Retry with git lfs push --all origin or git lfs pull. If it persists check the hub’s storage status.Severity: error · HTTP: 502
Message: Repository {repo} does not exist on the hub.Why: The repo name is mistyped or you are not a member of its project.Fix: List repos with weld repo list.Severity: error · HTTP: 404
Message: gh (the GitHub CLI) was not found: {detail}Why: weld invite --github adds the collaborator with the GitHub CLI, which is not installed or not on PATH.Fix: Install it (https://cli.github.com , e.g. brew install gh), run gh auth login, then retry; or drop –github and add them on github.com.Severity: error
Message: gh is not signed in to GitHub: {detail}Why: The GitHub CLI has no valid login, so it cannot add a collaborator.Fix: Run gh auth login (an account with admin access to the repo), then retry.Severity: error
Message: GitHub refused to add {login} to {repo}: {detail}Why: The repo slug or GitHub login is wrong, or your GitHub account is not an admin of the repo.Fix: Check the login and --repo <owner/repo>, and that gh auth status shows an admin of that repo; then retry (it is safe to repeat).Severity: error
Message: No online node has the role and capabilities for a {kind} job.Why: The node with the right role (e.g. a Windows build PC) is offline or asleep.Fix: Wake the machine, or add the role to another node with weld node role add <role>.Severity: warning · HTTP: 409
Message: Job {job} was rejected because its signature does not verify.Why: The job was tampered with or signed by an unknown key.Fix: Re-submit the job from a trusted node. If you did not submit it, tell your hub owner.Severity: error · HTTP: 403
Message: Job {job} ({kind}) exceeded its {timeout} timeout.Why: The tool hung, or the machine was too slow or went to sleep.Fix: Check the job logs with weld job logs {job} and retry; raise the timeout for large builds.Severity: error
Message: Job {job} needs approval from the owner of {node}.Why: Arbitrary commands from another person always need the node owner’s approval.Fix: The node owner approves with weld job approve {job} or on the dashboard.Severity: info · HTTP: 202
Message: The {kind} process for job {job} exited with {exit}.Why: The tool crashed or was killed (for example out of memory).Fix: Read the logs with weld job logs {job}; known crashes are matched automatically by weld doctor.Severity: error
Message: Job {job} may not read secret {name}.Why: The secret is not granted to this job kind, or the lease expired.Fix: Grant the secret to the job kind in project settings.Severity: error · HTTP: 403
Message: Job {job} was cancelled by {by}.Why: Someone cancelled it.Fix: Re-submit it if it is still needed.Severity: info
Message: {detail}Why: See the message and the job log.Fix: Install the engine from the Epic Games Launcher, or set WELD_UE_ROOT to an engine folder.Severity: error
Message: {detail}Why: See the message and the job log.Fix: Install the engine version the project asks for, or update the project’s EngineAssociation.Severity: error
Message: {detail}Why: See the message and the job log.Fix: Check the .uproject file exists and is valid JSON.Severity: error
Message: {detail}Why: See the message and the job log.Fix: Read the first compiler error in the job log (weld jobs logs <id>).Severity: error
Message: {detail}Why: See the message and the job log.Fix: Read the linker error in the job log; a clean rebuild often helps.Severity: error
Message: {detail}Why: See the message and the job log.Fix: Read the cook errors in the job log; usually a broken asset reference.Severity: error
Message: {detail}Why: See the message and the job log.Fix: Install the platform SDK (Xcode, Windows SDK, Android SDK) on the build node.Severity: error
Message: {detail}Why: See the message and the job log.Fix: Read the job log (weld jobs logs <id>).Severity: error
Message: {detail}Why: See the message and the job log.Fix: Open the project once in Xcode, accept the license (sudo xcodebuild -license) and retry.Severity: error
Message: {detail}Why: See the message and the job log.Fix: Run the job on a node with the right OS (--os).Severity: error
Message: {detail}Why: See the message and the job log.Fix: Check the packaged build exists and runs on this node.Severity: error
Message: {detail}Why: See the message and the job log.Fix: Raise the timeout or check the game for a hang at startup.Severity: error
Message: {detail}Why: See the message and the job log.Fix: Read the import log in the job output; check the file format.Severity: error
Message: {detail}Why: See the message and the job log.Fix: Check disk space and permissions, then retry weld game new.Severity: error
Message: {detail}Why: See the message and the job log.Fix: Pick a new directory or remove the existing one.Severity: error
Message: {detail}Why: See the message and the job log.Fix: Use letters, digits and _, starting with a letter.Severity: error
Message: {detail}Why: See the message and the job log.Fix: Check the tool is installed and executable.Severity: error
Message: {detail}Why: See the message and the job log.Fix: Raise the job timeout or check the tool for a hang.Severity: error
Message: {detail}Why: See the message and the job log.Fix: Check the path exists and that you have permission to read/write it.Severity: error
Message: {detail}Why: Another MCP server (e.g. a community unreal-mcp) answers on the editor’s MCP port, so Weld won’t send it any changes.Fix: Stop the other server or move it off the port, enable ModelContextProtocol + ToolsetRegistry (weld game doctor --fix), then weld game open.Severity: warning
Message: {detail}Why: The project doesn’t enable AllToolsets/EditorToolset or the Weld toolset, or the editor was opened before they were added.Fix: Run weld game doctor --fix, then restart the editor (weld game open).Severity: error
Message: {detail}Why: The editor rejected the call, or is busy compiling or in Play-In-Editor.Fix: Read the error and the editor’s Output Log (LogModelContextProtocol), then retry.Severity: error
Message: {detail}Why: The .uproject doesn’t enable the plugins Weld uses to talk to the editor.Fix: Run weld game doctor --fix (enables them in the .uproject), then reopen the editor (weld game open).Severity: warning
Message: {detail}Why: See the message and the job log.Fix: Install Blender or set WELD_BLENDER to its executable.Severity: error
Message: {detail}Why: See the message and the job log.Fix: Read the Blender output in the job log.Severity: error
Message: {detail}Why: See the message and the job log.Fix: Run the job on a node with a supported GPU (--tool gen3d).Severity: error
Message: {detail}Why: See the message and the job log.Fix: Retry, or regenerate from a different concept image.Severity: error
Message: {detail}Why: See the message and the job log.Fix: Retry; check the image provider key in the project secrets.Severity: error
Message: {detail}Why: See the message and the job log.Fix: Check weld status (hub online?) and retry.Severity: error
Message: {detail}Why: See the message and the job log.Fix: Regenerate with notes, or start over with a new brief.Severity: error
Message: {detail}Why: See the message and the job log.Fix: Follow the message; resume with weld asset make --resume <dir>.Severity: error
Message: {model} is gated on Hugging Face: this node can’t download it yet.Why: The model’s license must be accepted on its Hugging Face page (DINOv3 waits for a manual approval by Meta) and this machine must be logged in to that account. Still waiting: {models}.Fix: Accept the license at {url} (wait for the approval email), then on this machine run {login} and re-run weld setup --roles gpu-gen (it resumes; finished downloads are kept).Severity: error
Message: {asset} was made with {model} ({license}), which this project’s model license policy does not allow.Why: Its provenance ({file}) lists a model whose license is not in the allowlist: {allowed}.Fix: Regenerate the asset with an allowed model (TRELLIS.2 + FLUX.1 [schnell] are), or remove it. If your jam’s rules permit that license, add it to [assets] model_licenses in .weld/project.toml.Severity: error
Message: Setting up {part} failed at {step}: {command} exited with {exit}.Why: Last output: {tail}Fix: Read the step log {log}, fix the cause, then re-run weld setup --roles gpu-gen (finished steps are skipped).Severity: error
Message: {tool} is needed to build TRELLIS.2’s CUDA extensions but was not found.Why: The CUDA 12.4 toolkit (nvcc) and, on Windows, Visual Studio 2022 Build Tools with the C++ workload must be installed before the extensions can be compiled.Fix: Run weld setup --roles gpu-gen: it installs the CUDA 12.4 toolkit (toolkit only, never the driver) and the Build Tools after asking.Severity: error
Message: No Unreal Engine {version} install was found.Why: UE is not installed, or installed in a non-default location.Fix: Run weld setup --roles build (installs the Epic Games Launcher and prints the steps), then install UE {version} from the launcher; or set WELD_UE_ROOT to the engine folder.Severity: warning
Message: Unreal Engine {version} is installed, but projects need {required}.Why: Weld’s template and MCP integration target a specific UE version.Fix: Install UE {required} alongside your current version from the Epic Games Launcher.Severity: warning
Message: The Unreal editor MCP server at {url} is not responding.Why: The editor is closed, the Model Context Protocol plugin is disabled, or it uses another port.Fix: Open the project in the Unreal editor and enable the Model Context Protocol plugin.Severity: warning
Message: Blender was not found.Why: Blender is not installed or not on PATH.Fix: Run weld setup --roles asset (installs Blender after asking), or install Blender 4.x yourself and set WELD_BLENDER to its executable.Severity: warning
Message: Blender crashed while running step {step} (exit {exit}).Why: Usually a bad mesh, an out-of-memory condition or a GPU driver issue.Fix: Check the job log; the step will be retried once with CPU rendering. Known crash signatures are matched by weld doctor.Severity: error
Message: nvidia-smi is not available, so the GPU cannot be used.Why: The NVIDIA driver is not installed or is broken after an update.Fix: Install the current NVIDIA Studio or Game Ready driver and reboot.Severity: warning
Message: CUDA {required} is required for {kind} but was not found.Why: The CUDA runtime is missing or the driver is too old for it.Fix: Update the NVIDIA driver; the Python environment ships its own CUDA runtime.Severity: error
Message: {kind} needs {required} of VRAM but only {available} is free.Why: Another program (often the Unreal editor or a game) is using GPU memory.Fix: Close GPU-heavy programs, or route the job to another node.Severity: error
Message: Building {target} failed.Why: A compile error, a missing SDK, or a stale intermediate folder.Fix: Read the first error in the job log. For stale builds delete Intermediate/ and Binaries/ and rebuild.Severity: error
Message: Importing {asset} into Unreal failed: {detail}.Why: The file is malformed, uses an unsupported feature, or the editor is busy.Fix: Open the asset in the library to inspect it, then re-run the import job.Severity: error
Message: Unreal Engine {version} can’t build or package on this PC: missing {missing}.Why: UnrealBuildTool needs Visual Studio 2022 Build Tools with MSVC 14.44 (14.44.35211 or newer), a Windows 11 SDK (10.0.22621) and the .NET Framework 4.8 SDK plus 4.6.2 targeting pack. Without the .NET Framework SDK packaging fails with “Could not find NetFxSDK install dir”.Fix: Run weld setup --roles build: after asking, it adds the missing components to your Visual Studio install with Microsoft’s installer (Windows asks for permission). Manually: Visual Studio Installer → Modify → Individual components.Severity: warning · Auto-fix: weld doctor (install-prereqs)
Code
Title
Severity
WELD-E7001 Claude Code is not installed
error
WELD-E7002 Weld Claude Code plugin is not installed
error
WELD-E7003 Claude Code telemetry is not routed to weld
warning
WELD-E7004 Claude Code settings are invalid JSON
error
WELD-E7005 Agent budget exceeded
warning
WELD-E7006 Agent run failed
error
WELD-E7007 Claude Code is too old
warning
WELD-E7008 Claude Code hooks cannot find weld
error
WELD-E7009 The Weld plugin’s MCP header helper is broken
error
WELD-E7010 The node rejects the Weld plugin’s MCP token
error
WELD-E7020 Claude Code is not signed in
error
Message: The claude command was not found.Why: Claude Code is not installed or not on PATH.Fix: Run weld setup: it shows Anthropic’s official Claude Code installer command for your OS and runs it after asking. To install it yourself, follow Anthropic’s Claude Code setup instructions, then open a new terminal.Severity: error · Auto-fix: weld doctor (install-prereqs)
Message: The weld plugin is not installed or not enabled in Claude Code.Why: It was uninstalled or disabled, or weld node did not finish setup.Fix: Run weld doctor --fix to reinstall it (asks first), then restart your Claude sessions.Severity: error · Auto-fix: weld doctor (reinstall-plugin)
Message: ~/.claude/settings.json is missing {missing}.Why: Claude Code ignores OTel settings in project files, so weld writes them into your user settings; they were removed or never written.Fix: Run weld doctor --fix to merge them back in (asks first; other settings are preserved).Severity: warning · Auto-fix: weld doctor (write-otel-settings)
Message: {path} is not valid JSON: {detail}.Why: The file was edited by hand.Fix: Fix the JSON syntax; weld never overwrites a file it cannot parse.Severity: error
Message: Agent {agent} reached its budget of {budget}.Why: The run used more tokens than its cap allows.Fix: Raise the budget in the agent definition, or let it resume next period.Severity: warning
Message: Agent {agent} failed: {detail}.Why: Headless claude -p exited with an error, often due to auth or rate limits.Fix: Run claude interactively once to check your login, then retry.Severity: error
Message: Claude Code {version} is installed but weld needs {required} or newer.Why: The weld plugin uses hook and plugin features from newer releases.Fix: Update Claude Code (claude update).Severity: warning
Message: The Weld hooks in Claude Code run {command}, which does not exist.Why: weld moved or was reinstalled, or the plugin was installed before weld was on this machine’s PATH (apps started from the Dock/Start menu do not see your shell PATH).Fix: Run weld node repair: it regenerates the plugin so the hooks call this weld by absolute path, then restart your Claude sessions.Severity: error
Message: {command} (the plugin’s headersHelper) did not print the node’s Authorization header: {detail}Why: Claude Code runs this command to get the local API token for the Weld MCP server; it must print exactly one JSON object on stdout. A moved or old weld, or extra output, breaks it, and Claude Code then reports the MCP server as failed.Fix: Run weld node repair (regenerates the plugin with this weld’s absolute path), then restart your Claude sessions.Severity: error · Auto-fix: weld doctor (reinstall-plugin)
Message: The node at {url} answered HTTP {status} to the header {command} prints.Why: The node was started with a different local API token than the one the helper reads (another WELD_HOME, or the token file was recreated while the node kept running).Fix: Restart the node (weld doctor --fix restarts the service, or stop weld node run and start it again), then restart your Claude sessions.Severity: error · Auto-fix: weld doctor (restart-service)
Message: {bin} auth status reports that Claude Code is not signed in on this machine.Why: Nobody has logged in to Claude Code as this user yet, the login expired, or the node runs as a different user (e.g. a service) than the one who signed in.Fix: Run claude auth login (or start claude once and sign in) as the user that runs the Weld node, then weld doctor. Agent jobs (critic, merge agent, improver) fail until then.Severity: error
Message: Could not download the release manifest from {url}.Why: The hub and the release mirror are unreachable.Fix: Check your connection and retry weld update. Updates never interrupt work; they retry at idle.Severity: warning
Message: The release manifest signature does not verify against the embedded release key.Why: The manifest was tampered with, corrupted in transit, or signed with a different key.Fix: Do not install it. Report this to the Weld maintainers with weld doctor --share.Severity: fatal
Message: The downloaded weld {version} does not match its published SHA-256.Why: The download was truncated or modified in transit.Fix: Retry weld update; the bad download has been deleted.Severity: error
Message: Release {version} has no build for {target}.Why: This platform is not part of the release matrix, or the build failed for it.Fix: Stay on your current version, or build from source with cargo install --path crates/weld-cli.Severity: warning
Message: Replacing the weld binary at {path} failed: {detail}.Why: The file is locked (Windows antivirus) or the directory is not writable.Fix: Close other weld processes and retry, or reinstall weld manually.Severity: error
Message: weld {version} failed its health check and was rolled back to {previous}.Why: The new version did not start correctly on this machine.Fix: Nothing to do; you are on the previous version. Run weld doctor --share to help fix the release.Severity: warning
Message: There is no previous weld binary at {path}.Why: No update has been installed since weld was installed, or the backup was deleted.Fix: Reinstall the version you want manually.Severity: error
Message: No release signing key was found in {source}.Why: Signing needs the ed25519 private key, which is only available to release automation.Fix: Set WELD_RELEASE_KEY (base64 32-byte seed) or pass --key-file; generate one with weld release keygen.Severity: error
Message: The release manifest could not be parsed: {detail}.Why: The manifest was edited by hand or written by an incompatible tool.Fix: Regenerate it with weld release set and re-sign.Severity: error
Message: {provider} API call {operation} failed with {status}: {detail}.Why: Invalid credentials, quota limits, a name conflict, or a provider outage.Fix: Read the provider message above. Provisioning is idempotent: fix the issue and re-run the same command.Severity: error
Message: {variable} is not set.Why: Provisioning needs API tokens for the compute provider (DigitalOcean or Hetzner) and Cloudflare.Fix: Export {variable} (see docs/runbooks/provision.md) and re-run.Severity: error
Message: Restoring the hub from {source} failed: {detail}.Why: Backups are missing or unreadable, or the new server could not be prepared.Fix: Check the bucket contents with your R2 dashboard and retry weld restore; the old hub (if any) is untouched.Severity: error
Message: Another weld process is installing an update (lock at {path}).Why: Two update checks overlapped.Fix: Wait a minute and retry. Delete the lock file only if no weld process is running.Severity: warning
Message: The hub could not update itself to {version}: {detail}Why: The hub’s background updater (WELD_HUB_UPDATE_CHANNEL) or its privileged helper (weld-hub-update.path / weld-hub-update.service) could not stage, verify or install the release.Fix: Check journalctl -u weld-hub-update -n 50 and journalctl -u weld-hub -n 50 on the hub. If the helper units are missing, install them (docs/hub-ops.md, “Automatic updates”) or update by hand with weld hub upgrade --ssh root@<hub>.Severity: error
Message: Upgrading the hub at {host} failed: {detail}Why: A step of weld hub upgrade (download, checksum, install, restart or health check) failed on the hub.Fix: Read the step output above. The previous binary is kept as /usr/local/bin/weld-hub.prev; if the hub is down run weld hub upgrade --ssh <host> --rollback.Severity: error
Message: .weld/ship.toml is invalid: {detail}Why: The file has a typo, an unknown key, or a value Weld can’t use.Fix: Fix the file (see docs/runbooks/jam-day.md#ship-config for a complete example), then rerun weld ship --dry-run.Severity: error
Message: butler (itch.io’s upload tool) is not installed on this machine.Why: weld ship uploads to itch.io with butler; it is not on PATH or in Weld’s tools folder.Fix: Run weld ship butler --install (downloads the official build from broth.itch.zone), or install it from https://itch.io/docs/butler/ and put it on PATH.Severity: error
Message: No itch.io credentials for butler.Why: Neither BUTLER_API_KEY is set nor has butler login been run on this machine (remote builds lease the Weld secret BUTLER_API_KEY).Fix: Create a key at https://itch.io/user/settings/api-keys , then export BUTLER_API_KEY=... (local) or weld secret set BUTLER_API_KEY (remote builds), or run butler login.Severity: error
Message: butler push to {target} failed.Why: butler exited with an error (network, wrong user/game, or a revoked key); its last output is shown above.Fix: Check the itch target in .weld/ship.toml matches your itch.io page, that the game page exists, then retry weld ship --skip-package.Severity: error
Message: The packaged build failed its smoke test: {detail}Why: An automation test failed or the game crashed when launched from the packaged build.Fix: Fix the failing test (weld game smoke --packaged <exe> reproduces it), or ship anyway with --allow-failing-smoke if you know the failure is harmless.Severity: error
Message: Packaging {platform} for ship failed: {detail}Why: BuildCookRun failed locally or on the build node.Fix: Read the log path shown above; weld game package reproduces it locally, weld jobs logs <id> shows a remote build.Severity: error
Message: Could not create the ship zip at {path}.Why: Disk full, a file locked by a running game, or no write permission in .weld/out/ship.Fix: Close the game, free disk space, and retry with weld ship --skip-package.Severity: error
Message: ffmpeg is not installed on this machine.Why: weld ship video records the screen with ffmpeg.Fix: Install it (macOS: brew install ffmpeg; Windows: winget install Gyan.FFmpeg; Linux: sudo apt install ffmpeg), or record with OBS and trim to 30–60 s.Severity: error
Message: The {step} step on the build node failed: {detail}Why: The job could not be scheduled (no matching node online) or failed on the node.Fix: Check weld jobs list and weld node status; make sure the Windows node is online with Unreal installed, then rerun weld ship --channel windows.Severity: error
Message: Could not change the cluster’s release policy: {detail}Why: The hub refused the change (not a hub admin, or hub flags override it) or has no release to pin.Fix: Run as a hub admin; if WELD_HUB_RELEASE_PIN/CHANNEL are set in the hub’s env file, change them there instead.Severity: error
Message: Gameplay capture failed: {detail}Why: ffmpeg could not open the screen (missing Screen Recording permission on macOS, or no display).Fix: macOS: allow your terminal in System Settings > Privacy & Security > Screen Recording, then retry; or record with OBS.Severity: error
Message: Only {free} free on {mount} (Weld recommends at least {required}).Why: LFS caches, builds and ML models are large.Fix: Free space, or let weld evict old caches with weld cache prune.Severity: warning
Message: {mount} is full ({free} free).Why: Writes are failing, which can corrupt caches and builds.Fix: Free space now: weld cache prune, then remove old builds and DDC folders.Severity: fatal · HTTP: 507
Message: This machine’s clock differs from the hub by {skew}.Why: Time sync is disabled or failing. Large skew breaks TLS, token expiry and event ordering.Fix: Enable automatic time sync (macOS: System Settings → General → Date & Time; Windows: Settings → Time → Sync now; Linux: timedatectl set-ntp true).Severity: warning
Message: Weld cannot {action} {path}.Why: The file is owned by another user (often after running weld with sudo).Fix: Fix ownership, e.g. sudo chown -R $(whoami) {path}.Severity: error
Message: Writing the diagnostic bundle to {path} failed: {detail}.Why: The directory is not writable or the disk is full.Fix: Pass another location with weld doctor --bundle <path>.Severity: warning
Message: This machine appears to be offline.Why: Wi-Fi/Ethernet is down or DNS is not working.Fix: Reconnect. Weld keeps working offline and syncs when you are back.Severity: warning
Message: This matches known issue {id}: {title}.Why: {cause}Fix: {fix}Severity: warning
Message: {os}/{arch} is not a supported platform.Why: Weld ships for macOS arm64, Windows x64 and Linux x64/arm64.Fix: Use a supported machine, or build from source.Severity: warning
Message: The weld node is not installed as a background service.Why: Service installation is opt-in for nodes, so the node only runs while weld node run is open.Fix: Run weld node install-service to start the node at login and keep it running.Severity: info · Auto-fix: weld doctor (install-service)
Message: Downloading the Weld source for {version} failed: {detail}.Why: GitHub is unreachable or the release tag does not exist.Fix: Claude can still debug with the diagnostic bundle alone. Ask your hub owner for the Weld source at {version} if you need it.Severity: warning
Message: Weld hit an unexpected error: {detail}.Why: This is a bug in Weld.Fix: Run weld doctor --ai to investigate, or weld doctor --share to report it.Severity: error
Message: {tool} was not found on PATH.Why: The tool is not installed or not on PATH for this shell or service.Fix: Install {tool} and make sure it is on PATH.Severity: error
Message: Installing {name} failed: {command} exited with {exit}.Why: {detail}Fix: Run it yourself: {command} (or {manual}), then weld setup. The full installer output is in {log}.Severity: error
Message: Weld can’t install {name} on this machine: {why}.Why: Weld installs prerequisites with winget (Windows), Homebrew (macOS) or apt/dnf (Linux), or the vendor’s official installer.Fix: Install it yourself: {manual}. Then run weld setup.Severity: warning
Message: {count} prerequisite(s) are missing and were not installed: {names}.Why: {why}Fix: Run weld setup --yes to install them (the commands are printed above), or run those commands yourself.Severity: warning · Auto-fix: weld doctor (install-prereqs)
Message: The {name} installer finished, but Weld still can’t find {name}.Why: Some installers only update PATH for new terminals, or need a restart; or the install was cancelled in its own window.Fix: Open a new terminal and run weld setup again. If it is still missing: {manual}. Installer output: {log}.Severity: warning
Message: {tools} is installed in {dir}, but that folder is not on your PATH, so new terminals can’t find it.Why: Its installer put it in a per-user folder and did not add that folder to the PATH new terminals get (or the change was undone).Fix: Run weld setup (or weld doctor --fix) to add {dir} to your PATH, then open a new terminal. Manually: {manual}.Severity: warning · Auto-fix: weld doctor (install-prereqs)
