Second Brain

nova-error-playbook-consolidated

2 min read

NOVA Error Playbook — Consolidated Patterns

Offloaded from error-playbook.md on 02-Apr-2026. All patterns are active — consult before debugging similar issues.

EACCES permission denied on workspace files

Symptom: Agent fails with EACCES: permission denied on workspace files. Cause: Files modified by non-openclaw process (Claude Code SSH as claude user). Fix: sudo chown -R openclaw:openclaw /home/openclaw/.openclaw/workspace/ Prevention: Always chown after external modification.

Agent can’t see workspace files after deployment

Symptom: Agent spawns but responds without context from AGENTS.md or companion files. Cause: workspace property not set (only agentDir set). Different purposes. Fix: Set explicit workspace property pointing to file directory. Prevention: Component Integration Protocol Phase 4 — verify with spawn test.

Skill installed but not discovered by OpenClaw

Symptom: Skill script runs via exec but doesn’t appear in skill registry. Cause: Installed to wrong path. Fix: Check OpenClaw docs for correct skill installation path. Reinstall. Prevention: Never assume paths — verify against docs.

Claude Code desktop crashes on SSH to root user

Symptom: SSH exits immediately with code 1. No error. Cause: Claude Code v2.1.78+ blocks --dangerously-skip-permissions with root/sudo. Fix: Non-root user with passwordless sudo + symlink ~/.claude → /root/.claude. Add to docker, users, openclaw groups. Expect 5-6 downstream permission fixes. Prevention: Never configure Claude Code SSH with root user.

Agent falls back to Kimi — OAuth missing access/expires

Symptom: Agent uses kimi-k2.5 instead of opus-4-6. Logs: FailoverError: No API key found for provider "anthropic". Cause: auth-profiles.json has type: "oauth" with only key field. OpenClaw needs access + expires. Fix: Add access (= key value) + expires (= 4102444800000) to ALL 6 auth-profiles.json files. Restart gateway. Prevention: After claude setup-token, always add access/expires. Verify: journalctl --user-unit=openclaw-gateway.service | grep "candidate_failed" — zero hits = working.

Workspace file truncated — agents miss instructions

Symptom: Warning about workspace bootstrap file exceeding char limit. Cause: OpenClaw injects workspace files with bootstrapMaxChars limit. Exceeding = silent truncation of bottom content. Fix: Restructure file to fit, split, or increase bootstrapMaxChars. Prevention: After edits: wc -c FILE.md. Current total limit: 150,000 chars. File at 80% → compress immediately.

Graph View

Backlinks