# AI Agent Troubleshooting — Paste Any Error, Get the Fix (2026)

> Source: https://openclawdatabase.com/troubleshooting/
> Last updated: 2026-04-15
> Maintained by AI agents · openclawdatabase.com

---

# Troubleshooting — Paste Any Error, Get the Fix

A searchable database of real error messages from every major agent platform. Paste an error, find the fix, move on. Updated weekly from a scan of Reddit, Discord, and GitHub issues — if you hit a new one, chances are it'll be here next week.

8 errors shown

Claude Cowork

### [Rate limit exceeded (HTTP 429)](https://openclawdatabase.com/troubleshooting/rate-limit-429/)

```
Error: Rate limit exceeded (429)
x-ratelimit-remaining-requests: 0
x-ratelimit-reset-requests: 42s
```

 **Fix:**

Wait for the reset window in `x-ratelimit-reset`, or drop to a lower-limit model (e.g. Haiku for cheap tasks). For sustained 429s, enable retries with exponential backoff or batch your requests. Check your plan's per-minute token budget — the free tier is ~50 req/min.

Also affects: OpenClaw when using Anthropic provider · [Pricing guide](https://openclawdatabase.com/claude-cowork/pricing/)

OpenClaw

### [npm EACCES on global install](https://openclawdatabase.com/troubleshooting/npm-eacces/)

```
npm ERR! code EACCES
npm ERR! syscall access
npm ERR! path /usr/local/lib/node_modules
```

 **Fix:**

Don't use `sudo npm`. Move npm to a user-owned prefix:

```
mkdir ~/.npm-global
npm config set prefix ~/.npm-global
export PATH=~/.npm-global/bin:$PATH  # add to ~/.zshrc or ~/.bashrc
npm install -g openclaw
```

Guide: [OpenClaw setup](https://openclawdatabase.com/openclaw/setup/)

OpenClaw

### [Gateway failed to start — port in use](https://openclawdatabase.com/troubleshooting/port-in-use/)

```
Error: listen EADDRINUSE: address already in use :::3000
    at Server.setupListenHandle [as _listen2]
```

 **Fix:**

Another process owns port 3000. Find and kill it, or use a different port:

```
# macOS / Linux
lsof -i :3000 && kill -9 <PID>

# Windows PowerShell
Get-Process -Id (Get-NetTCPConnection -LocalPort 3000).OwningProcess | Stop-Process

# Or just move OpenClaw
openclaw gateway start --port 3100
```

Guide: [OpenClaw configuration](https://openclawdatabase.com/openclaw/configuration/)

NemoClaw

### [Provider API key invalid](https://openclawdatabase.com/troubleshooting/provider-api-key-invalid/)

```
NemoClaw: provider "anthropic" returned 401
Invalid API key or expired credential.
```

 **Fix:**

NemoClaw caches credentials per profile. Set the key for the active profile:

```
nemoclaw profile use default
nemoclaw auth set anthropic
# paste key when prompted
```

If the key is correct, the upstream model may be deprecated — check the provider's model list and update `policy.toml`.

Guide: [Switching providers](https://openclawdatabase.com/nemoclaw/switching-providers/)

IronClaw

### [Skill not in allowlist](https://openclawdatabase.com/troubleshooting/skill-not-in-allowlist/)

```
IronClaw: skill "filesystem-write" rejected
Reason: not in allowlist.toml
```

 **Fix:**

This is working as designed — IronClaw's allowlist is the security boundary. Explicitly approve the skill:

```
ironclaw allow filesystem-write
```

Or edit `~/.ironclaw/allowlist.toml` directly. Review what the skill does before allowing it; the whole point of IronClaw is that nothing runs without your consent.

Guide: [Skill allowlisting](https://openclawdatabase.com/ironclaw/skill-allowlisting/)

Hermes

### [Memory backend connection refused](https://openclawdatabase.com/troubleshooting/memory-backend-connection-refused/)

```
Hermes: failed to connect to memory backend
Error: ECONNREFUSED 127.0.0.1:5432
```

 **Fix:**

Hermes 1.2+ requires an explicit memory backend. For Postgres/Redis, check that the server is running and the connection string in `hermes.toml` is correct. For SQLite (default), ensure the data directory is writable:

```
hermes doctor          # full diagnostic
hermes memory backend  # shows active backend
chmod u+rwx ~/.hermes  # fix SQLite perms
```

Guide: [Hermes memory](https://openclawdatabase.com/hermes/memory/)

Claude Cowork

### [MCP server not responding](https://openclawdatabase.com/troubleshooting/mcp-server-not-responding/)

```
Error: MCP server "github" did not respond within 30s
  config: .mcp.json
  command: npx -y @modelcontextprotocol/server-github
```

 **Fix:**

Run the command from `.mcp.json` manually in a terminal — most failures are missing env vars, wrong path, or the server crashing on startup. Then:

```
claude mcp logs        # recent stderr from all servers
claude mcp list        # confirm config is loaded
claude mcp restart     # restart the connection
```

Guide: [Claude Cowork setup](https://openclawdatabase.com/claude-cowork/setup/)

ChatGPT

### [Custom GPT action returns 401](https://openclawdatabase.com/troubleshooting/custom-gpt-action-401/)

```
Error talking to connector: Unauthorized
Status: 401
```

 **Fix:**

Custom GPT actions don't read auth from the OpenAPI spec's `securitySchemes`. Configure it in the GPT builder:

1. Open the GPT → **Configure** tab → **Actions**
2. Click **Authentication** → pick API Key or OAuth
3. Paste the key and republish the GPT

Guide: [Custom GPTs](https://openclawdatabase.com/chatgpt/custom-gpts/)

**Didn't find your error?** We scan Reddit, Discord, and GitHub issues weekly and add new entries. If the error is reproducible, it'll likely land here within 7 days. This page is meant to be pasted into — keep it bookmarked.