| Anything unclear about the machine | nomarmy doctor, then nomarmy health |
A job shows orphaned with no result | Jobs run inside the MCP server of the coordinator session that started them, so closing or restarting that session ends them; the error says how its server stopped. Dispatch again from a session that stays open until the job finishes (nomarmy jobs --wait <job id>). A job another open session is running shows running, with runningIn naming that session's server |
nomarmy update or doctor --fix says an OpenClaw upgrade step failed | The error's last lines are printed under the step. A plugin install is retried once; if it still fails on openclaw: latest, OpenClaw and its plugins go back to the exact release you had. Run nomarmy doctor --fix again later. If it says the newer release migrated OpenClaw's state and it's staying on that release, the earlier one can't read that state: move the roles it names to another model (nomarmy army assign) until a fix |
A worker's commands come back Aborted, even simple reads, or jobs fail in ways that make no sense (macOS, Windows) | macOS: the Podman VM is too small: every sandbox, verification run and image build shares its memory, and Podman's default is 2 GiB. nomarmy sandbox shows it; nomarmy sandbox --memory 8 resizes it (doctor fails below 4 GiB). Windows: Podman runs inside WSL and shares WSL2's memory (about half the machine by default); raise memory= under [wsl2] in %UserProfile%\.wslconfig, then wsl --shutdown |
Every sandbox fails to start with error during chown ... permission denied or insufficient UIDs or GIDs available in user namespace, often right after the Podman VM restarted | Rootless Podman lost its subordinate ID ranges (/etc/subuid, /etc/subgid emptied). nomarmy doctor detects it; nomarmy sandbox --repair restores them (it waits until no job is running, since it restarts Podman's containers) |
| The disk fills up with old images | nomarmy sandbox --prune removes images no container uses; nomArmy rebuilds its own when a job needs them |
No API key found for provider "llama-cpp" during e2e.sh | ./scripts/configure-openclaw.sh <profile>, then rerun |
Jobs on an api agent fail with No API key found | OpenClaw never saved its key, usually because agents.yml was written by hand. Export the agent's auth_env variable, then nomarmy agents register <name> |
A Claude subscription's test call or jobs fail with 401 while claude auth status says you're logged in | Claude Code's saved login went stale. claude auth logout && claude auth login, then nomarmy agents update <agent> --probe |
nomarmy doctor flags the Codex login expiring, or a fresh codex login doesn't help | Re-import it into OpenClaw with the command doctor prints. It includes --overwrite: without it, OpenClaw keeps the old profile (beta.9 and earlier printed it without) |
nomarmy doctor says OpenClaw's Codex plugin is missing @openai/codex-<platform>-<arch> | npm skipped an optional dependency when the plugin was installed, so its bundled Codex can't start. Run the command doctor prints: it installs that one package beside the plugin and copies it in (npm can't install inside the plugin itself) |
| An OpenClaw command fails with "This operation requires exclusive offline state ownership" | OpenClaw 2026.11 saves keys and sign-ins (models auth login, logout, paste-api-key, a Codex import) only while its Gateway is stopped. nomArmy's setup offers to stop it and starts it again when it finishes (not while jobs run). By hand: openclaw gateway stop --force, run the command, then openclaw gateway start. Health reads sign-ins without stopping it |
| A Grok (or other OpenClaw sign-in) test call or job fails with "Explicit auth order for xai has no usable profiles" | OpenClaw's isolated runs can't use a sign-in OpenClaw holds itself (openclaw/openclaw#124768). Run the agent through the Gateway: nomarmy agents update <agent> --route gateway (see the Gateway route) |
| An OpenClaw command fails with "OpenClaw state at ... is undergoing offline maintenance; retry when it finishes" | Another OpenClaw process holds its state database, which happens when no OpenClaw Gateway is running. It clears in seconds. nomArmy retries its own calls (health, a job's start) and makes health's one at a time; beta.12 and earlier could report "Codex has no unexpired account-ID (Codex import) profile" instead. Don't re-import the Codex login for that: each import leaves a backup holding credentials in ~/.openclaw-backups |
A job fails with, or is refused for, model_not_found | Your plan or OpenClaw can't run that model (nomArmy tests an unproven model before its first job). nomarmy agents list shows which roles use it; nomarmy army assign <role> <agent> <model> moves the role and tests the new model |
| A Muse Code job fails with a 403: "This API key is billed to a Muse Code subscription. Muse Code subscriptions cover requests from the Muse Code client only" | The agent was set up before beta.15 and sends Muse Code's key to Meta's API through OpenClaw's Meta plugin, which Meta now refuses. nomarmy health flags it. Run nomarmy agents remove <name> && nomarmy agents add subscription meta (it then runs through muse exec), and openclaw models auth logout meta:subscription to remove the old key copy |
| A Muse Code job or test call fails with "CLI backend muse-cli cannot enforce workspace-only tool policy" | OpenClaw 2026.11 limits file tools to the workspace and refuses Muse Code, which runs its own tools. beta.19 and later turn that limit off for Muse Code runs only: nomarmy update, then restart open sessions |
A model the catalog lists fails with Unknown model, after OpenClaw or a vendor plugin was updated (e.g. meta/muse-wonder-1.0) | OpenClaw's provider entry was written by the older plugin and lists its models explicitly. nomarmy doctor --fix adds the models the plugin now lists, with the plugin's own config step, and backs up openclaw.json first; nomarmy update does it too, and nomarmy health flags it |
| Verification fails on a missing package | Node: commit your lockfile (npm, pnpm, yarn and bun lockfiles and workspaces are installed). Python: list your requirements files under environment.python.requirements, or commit uv.lock, poetry.lock or a pyproject.toml |
| A job sits with no progress, or times out with no report, right after a lockfile changed | The sandbox image is rebuilding. A build stops after 30 minutes (NOMARMY_IMAGE_BUILD_TIMEOUT_MINUTES) and Playwright's browser install after 5 minutes per attempt. beta.4 and earlier hung for good on Playwright before 1.60, whose browser extraction never finishes on Node 26; nomArmy now works around it. If the repo matches the browser harness but its end-to-end tests run elsewhere, add exclude_harnesses: [browser-playwright] to .nomarmy.yml |
Every sandbox fails with SandboxProvisioningError ... container.env: no such file or directory (Linux) | The service running nomArmy or OpenClaw has systemd PrivateTmp=yes. OpenClaw writes sandbox files under /tmp/openclaw and ignores TMPDIR, so Podman can't see them. Set PrivateTmp=no in that unit and restart it; nomarmy doctor lists such units |
Verification is not_run with CNI network backend without the dnsname plugin (Linux) | Harness services such as mock-oidc are reached by name on a private Podman network, and Ubuntu's podman (CNI by default) doesn't install name resolution. sudo apt install golang-github-containernetworking-plugin-dnsname; nomarmy doctor checks for it. Podman's netavark backend (the only one in Podman 5) has it built in, but switching an existing install needs podman system reset, which deletes every container and image |
Scouts or worktree cleanup fail with git exited 255: error: failed to delete '<worktree>/.openclaw/sandbox-skills/skills': Permission denied (Linux, rootless Podman; nomArmy beta.9 and earlier) | The container runtime created OpenClaw's skills mount point in the worktree as the sandbox's root, which is a subordinate id outside it. nomArmy now creates that directory itself before each run and hands anything the sandbox left back to you before git touches the worktree, so new jobs don't hit it. For older worktrees, local_worker_cleanup or local_worker_sweep reclaims them first; by hand, podman unshare chown -R -h 0:0 <worktree> |
Verification fails with EACCES writing inside the checkout (Linux) | Rootless Podman older than 4.3 can't map your user into the sandbox. Upgrade Podman |
| A config change didn't take effect | nomarmy stop <profile> && nomarmy start <profile> for local inference (hosted setups have none); restart your coordinator after nomarmy connect or an update |
git worktree add fails with Filename too long (Git for Windows) | git config --global core.longpaths true. Job worktrees on Windows are made by Git inside WSL, which has no such limit |
| Not sure a setting fits your hardware | nomarmy sizing, or nomarmy sizing --check |