Openclaws on ErrorVault — Developer Error Code Dictionary

Fix clw-fs-not-found: OpenClaw filesystem not found error resolution

Fri, 18 Oct 2024 00:00:00 +0000

1. Symptoms

The clw-fs-not-found error in OpenClaw manifests during runtime initialization when the interpreter fails to locate the required Claw filesystem (.clw resources). Common indicators include:

Console output: Error: clw-fs-not-found: Filesystem at path '/path/to/claw-fs' not found. Aborting.
Application crash immediately after launch, often with exit code 101.

Log entries in openclaw.log:

[ERROR] [clw_fs_init] Failed to open directory: /default/claw-fs. Errno: 2 (No such file or directory)
[FATAL] clw-fs-not-found triggered.

No game assets load; black screen or minimal CLI output in interactive fiction sessions.
Affects both standalone binaries and embedded modes in tools like clawrun or openclaw-player.

This error blocks all further execution, as OpenClaw relies on the .clw filesystem for Blorb resources, story files, and metadata. Reproducible by running:

Fix clw-fs-timeout: OpenClaw filesystem operation timeout exceeded

Sat, 12 Oct 2024 00:00:00 +0000

1. Symptoms

The `clw-fs-timeout` error in OpenClaw manifests during filesystem operations like `clw_fs_read()`, `clw_fs_write()`, `clw_fs_open()`, or `clw_fs_sync()`. Applications receive return code `-CLW_FS_TIMEOUT` (typically `-1101`) or observe the error in logs:

[ERROR] clw_fs_read(/path/to/file): operation timed out after 5000ms


Key indicators:
- Operations hang indefinitely or abort after a fixed interval (default 5s).
- High CPU usage from polling loops in libclwfs.
- Intermittent failures on slow storage (e.g., SD cards, network FS like NFS over slow links).
- Stack traces show blocks in `clw_fs_wait_for_completion()` or `clw_fs_poll_fd()`.
- System logs (dmesg/syslog) may show underlying I/O delays: `slow SDMMC timeout` or `NFS server not responding`.

Use `strace` or `gdb` to confirm:

```c
// gdb session example
(gdb) bt
#0 clw_fs_wait_for_completion (ctx=0x1234, timeout_ms=5000) at clw_fs.c:456
#1 clw_fs_read (fd=3, buf=0x5678, len=1024) at clw_fs_ops.c:234

Affected platforms: Embedded Linux (e.g., Yocto builds), RTOS like FreeRTOS with OpenClaw POSIX layer, bare-metal ClawOS.

Fix clw-auth-disconnected: Resolve OpenClaw authentication disconnection during sessions

Fri, 04 Oct 2024 00:00:00 +0000

1. Symptoms

The `clw-auth-disconnected` error in OpenClaw manifests during authentication handshakes or active sessions. Clients log:

[ERROR] clw-auth-disconnected: Authentication stream closed unexpectedly (code: 0xA03)


Symptoms include:

- Abrupt session termination after initial auth success.
- Failed API calls returning 503-like responses with auth context.
- Network traces showing TCP RST or FIN-ACK from server post-auth packet.
- Client-side: `ClwAuthHandle` becomes invalid, `clw_auth_status()` returns `CLW_AUTH_DISCONNECTED`.
- High-frequency occurrences under load, e.g., >100 concurrent sessions.
- No data corruption; pure auth-layer disconnect.

Repro steps: Run OpenClaw client against a loaded server, simulate 5-10s latency spikes. Error rate spikes to 40% on unstable networks.

Logs often pair with:

[DEBUG] clw-net: Heartbeat timeout after 3000ms [WARN] clw-auth: Token refresh failed, seq=0xFF

Fix clw-llm-failure: OpenClaw LLM service connection or inference failure error

Tue, 01 Oct 2024 00:00:00 +0000

1. Symptoms

The clw-llm-failure error in OpenClaw manifests during LLM inference calls. Common indicators:

Console output: ERROR: clw-llm-failure: Failed to invoke LLM endpoint: [detailed message, e.g., 'HTTP 503 Service Unavailable']
Application halts on ClawLLM::infer() or clw_llm_generate().
HTTP status codes in logs: 429 (rate limit), 500 (internal server error), or connection refused.
No response payload; partial traces show successful init but failure on /v1/completions POST.

Example log snippet:

[2024-10-01T12:00:00Z] INFO: ClawLLM init with model=gpt-4o-mini, endpoint=https://api.openai.com/v1
[2024-10-01T12:00:01Z] ERROR: clw-llm-failure: Request to LLM failed. Code: -32603, Message: Internal JSON-RPC error.
[2024-10-01T12:00:01Z] FATAL: Inference aborted. Retries exhausted: 3/3
---

Runtime symptoms include:
- Spikes in CPU usage during retries.
- Increased latency (>10s per call).
- Docker containers restarting if using Claw in containerized envs.

This error blocks all downstream LLM-dependent pipelines, such as RAG systems or chatbots built on OpenClaw.

## 2. Root Cause

`clw-llm-failure` triggers when OpenClaw's ClawLLM client cannot complete an inference request. Core causes:

1. **Network/Connectivity**: Firewall blocks, DNS resolution fails, or proxy misconfig. OpenClaw uses HTTP/2 to LLM providers (OpenAI, Anthropic, etc.).
2. **Authentication**: Invalid/missing `CLAW_LLM_API_KEY` or expired tokens.
3. **Provider-Side Issues**: Model overload (e.g., GPT-4 rate limits), endpoint downtime, or unsupported model names.
4. **Configuration Mismatch**: Incorrect `base_url`, `model_id`, or payload format (e.g., missing `temperature` in JSON).
5. **Resource Exhaustion**: Local timeouts (<30s default), memory leaks in multi-threaded calls.
6. **JSON-RPC Parsing**: Malformed responses from LLM API not handled by ClawLLM v2.1+.

Inspect via `claw_debug --llm` flag for traces. Root cause often correlates with `curl -v` tests to the endpoint.

## 3. Step-by-Step Fix

Resolve `clw-llm-failure` systematically. Start with basics, escalate to code changes.

### Step 1: Verify Environment
```bash
# Check API key and endpoint
echo $CLAW_LLM_API_KEY | wc -c # >30 chars expected
curl -H "Authorization: Bearer $CLAW_LLM_API_KEY" https://api.openai.com/v1/models

Step 2: Update ClawLLM Config

Set robust defaults in claw_config.toml:

Fix clw-router-invalid: Invalid router configuration in OpenClaw framework

Wed, 18 Sep 2024 00:00:00 +0000

1. Symptoms

The clw-router-invalid error in OpenClaw manifests during application initialization or router setup phases. OpenClaw, a lightweight C++ web framework for high-performance routing, throws this error when the router configuration fails validation.

Common symptoms include:

Console/Log Output:

[ERROR] clw-router-invalid: Route '/api/users/{id' has unbalanced parameter braces at position 12
Router initialization failed. Aborting startup.

Runtime Behavior: The application crashes on startup with exit code 101. No HTTP server binds to the port (default 8080).

Openclaws on ErrorVault — Developer Error Code Dictionary

Fix clw-fs-not-found: OpenClaw filesystem not found error resolution

1. Symptoms

Fix clw-fs-timeout: OpenClaw filesystem operation timeout exceeded

1. Symptoms

The clw-fs-timeout error in OpenClaw manifests during filesystem operations like clw_fs_read(), clw_fs_write(), clw_fs_open(), or clw_fs_sync(). Applications receive return code -CLW_FS_TIMEOUT (typically -1101) or observe the error in logs:

Fix clw-auth-disconnected: Resolve OpenClaw authentication disconnection during sessions

1. Symptoms

The clw-auth-disconnected error in OpenClaw manifests during authentication handshakes or active sessions. Clients log:

Fix clw-llm-failure: OpenClaw LLM service connection or inference failure error

1. Symptoms

Step 2: Update ClawLLM Config

Fix clw-router-invalid: Invalid router configuration in OpenClaw framework

1. Symptoms

The `clw-fs-timeout` error in OpenClaw manifests during filesystem operations like `clw_fs_read()`, `clw_fs_write()`, `clw_fs_open()`, or `clw_fs_sync()`. Applications receive return code `-CLW_FS_TIMEOUT` (typically `-1101`) or observe the error in logs:

The `clw-auth-disconnected` error in OpenClaw manifests during authentication handshakes or active sessions. Clients log: