Troubleshooting
CLI Build Fails
Run:
pnpm install
pnpm build
Check tsconfig.json, missing dependencies, and local Node/pnpm versions.
Codex Sandbox Fails
Run:
x4 doctor host
x4 doctor devbox
codex sandbox linux /bin/true
Check Bubblewrap, uidmap, and AppArmor user namespace settings.
GitHub Auth Fails
Run:
x4 github app validate --repo owner/repo
Check GitHub App installation, private key path, permissions, and repo access.
Remote Worker Is Quarantined
Run:
x4 control inspect --job <control-job-id>
x4 control workers
Do not repair the worker until the failed workspace/artifacts have been inspected.
Preview URL Rejected
X4 rejects local-only URLs. Use a Tailscale 100.64.0.0/10 address or MagicDNS
.ts.net hostname:
x4 preview serve --host <tailnet-host>
Mastra Workflow Blocks
Check:
- issue labels and trusted actor;
- Code Assist SQLite state;
- implementation worktree path;
- Codex binary path;
- GitHub App credentials;
- deterministic test output;
implementation-blockedissue comments.