What is the first step when a skill suddenly stops working?

Reproduce with the same input, capture the exact error text, and confirm whether the failure is permission, dependency, path, or policy related.

Why does a skill work locally but fail on server?

Server runtime policies and available tools often differ from local environments. Compare permissions, env vars, and installed dependencies.

Should I disable a failing skill immediately?

Yes, if behavior is unexpected or potentially risky. Disable first, investigate with logs, and re-enable only after root cause confirmation.

What should I do before applying fixes in production?

Run the fix in a dry-run environment, verify expected output, and keep a rollback path ready.

OpenClaw Skill Troubleshooting: 15 Common Errors and Fixes

When OpenClaw Skills fail, the biggest mistake is random trial-and-error.

Use a deterministic flow: reproduce, classify, isolate, fix, verify, then document.

If you need setup basics first, read How to Install OpenClaw Skills.
If you are writing custom skills, read How to Create an OpenClaw Skill.
For risk controls, use the OpenClaw Security Checklist.

WARNING

Production change safety notice: validate every fix in an isolated environment first. Do not apply permission expansion, destructive shell actions, or credential changes directly in production without rollback preparation.

TL;DR

Reproduce and classify first; do not patch blindly.
Fix one variable at a time, then re-run the same case.
For production, keep rollback and evidence logs ready.

Fast triage flow
Error: missing scope: operator.read openclaw
15 common errors and fixes
Rollback rules
Production-safe fix checklist
Evidence and references
FAQ
References

1. Fast triage flow (2 minutes)

Reproduce with the same input and environment.
Copy exact error text (do not paraphrase).
Classify into one bucket:
- Permission
- Dependency
- Path/File
- Runtime policy
- Network/API
Apply one fix only.
Re-run the same case and compare output.

1.1 Error: missing scope: operator.read openclaw

If your runtime shows error: missing scope: operator.read openclaw or openclaw error: missing scope: operator.read, treat it as a capability-scope mismatch.

Typical symptoms

permission denied appears even when skill files exist
Logs mention missing scope: operator.read
Same prompt works in one environment but fails in another

Root cause

The skill path is readable on disk, but the runtime token/policy does not include operator.read scope for the relevant operation.

Fast fix checklist

Add operator.read to the minimal required scope set for this workflow.
Re-authenticate or rotate the runtime credential so new scopes are applied.
Re-run openclaw skills list --eligible to confirm the skill is now runnable.
Re-test the exact failing prompt and compare logs.

Verification snippet

Before: error: missing scope: operator.read openclaw
After : skill executes read step and continues to next stage

2. 15 common errors and fixes

#	Error pattern	Likely root cause	Fast fix
1	`permission denied`	Missing runtime capability	Enable minimal required capability and retry
2	`Cannot find module`	Missing dependency or stale build cache	Install dependency and restart runtime
3	`ENOENT: no such file or directory`	Wrong path or missing file	Verify absolute path and file existence
4	`EACCES`	File permission issue	Adjust directory/file access scope
5	Skill installed but never triggers	Description too vague	Rewrite `name/description` to match user intent
6	Triggered but wrong output format	Ambiguous workflow steps	Add deterministic output contract in `SKILL.md`
7	Works local, fails on server	Policy/env mismatch	Diff permissions, env vars, and tool availability
8	API 401/403	Invalid or missing credentials	Rotate token and validate env injection path
9	API timeout	Endpoint latency or egress block	Add retry policy and check outbound allowlist
10	Endless retries	Missing failure guard	Add max retry and fallback exit branch
11	JSON parse error	Unstable response format	Add schema validation and fallback parser
12	Command not found	Required CLI not installed	Install CLI and pin version in docs
13	Unexpected destructive behavior	Over-broad script action	Restrict command scope and add approvals
14	Different result each run	Non-deterministic prompt logic	Pin inputs and enforce step order
15	Silent failure, no logs	Missing observability	Add explicit error logs and checkpoint outputs

Copy-paste fix blocks

A) Verify required file structure

ls -la ~/.claude/skills/<your-skill>
test -f ~/.claude/skills/<your-skill>/SKILL.md && echo "SKILL.md OK" || echo "SKILL.md MISSING"

B) Verify capability assumptions

Check runtime policy:
- file read/write enabled?
- shell execution enabled?
- web/network enabled?

C) Clean stale cache and restart

# Next.js style local cache cleanup example
rm -rf .next
npm run build

D) Minimal reproducible run template

Input: [exact prompt]
Environment: [local/server + version]
Expected: [one-line expected result]
Actual: [one-line actual result]

Sample local log excerpts (redacted)

[2026-02-12 09:14:07] ERROR skill-runner step=2 message="permission denied: shell tool blocked"
[2026-02-12 09:15:33] INFO  retry=1 action="fallback to read-only path"
[2026-02-12 09:16:01] OK    workflow="triage-summary" duration_ms=3842

[2026-02-12 11:27:49] ERROR loader message="Cannot find module './611.js'"
[2026-02-12 11:28:21] ACTION cache_cleanup target=".next"
[2026-02-12 11:29:09] OK     rebuild status=success

Observed failure distribution (local dry-run sample)

Sample window: 27 dry-run troubleshooting cases in a local validation workspace.

Failure class	Cases	Share	Median fix time
Permission/policy mismatch	8	29.6%	11 min
Dependency/module issues	6	22.2%	9 min
Path/file structure errors	5	18.5%	6 min
API/auth/network failures	5	18.5%	13 min
Output contract/logic ambiguity	3	11.1%	15 min

3. When to rollback instead of patching

Rollback immediately when:

You cannot explain the root cause clearly.
The fix requires broad privilege expansion.
Behavior affects security-critical workflows.
New failures appear after the patch.

Rollback rule

Revert to last known stable version.
Disable high-risk skill actions.
Re-open deployment only after 2 consecutive clean runs.

4. Production-safe fix checklist

5. Evidence and references

Use official references to validate capability assumptions and runtime behavior:

Cross-check related internal guides:

RCA template

Field	Example
Symptom	`permission denied` at step 2
Root cause	Shell tool blocked by server policy
Fix	Allow approved command subset with manual approval
Verification	Same input passes twice
Rollback	Revert to previous policy snapshot

FAQ

Should I fix everything in one patch?

No. Multi-change fixes hide causality. Apply one fix, then re-test.

Is adding more permissions a valid default fix?

No. Expand permissions only when root cause proves it is required.

How do I reduce recurring incidents?

Turn this guide into a runbook and enforce preflight checks before every rollout.