> ## Documentation Index
> Fetch the complete documentation index at: https://docs.siclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Solutions for common setup and runtime issues.

## Node.js Version

Siclaw requires Node.js 22.19.0 or later.

```bash theme={null}
node --version
# Must be v22.19.0+
```

If you're on an older version, use [nvm](https://github.com/nvm-sh/nvm):

```bash theme={null}
nvm install 22
nvm use 22
```

## LLM Connection Failures

**Symptom**: "Failed to connect to LLM provider" or empty responses.

**Check**:

1. Open the active config file:
   ```bash theme={null}
   ls .siclaw/config/settings.json
   ```
2. Verify `baseUrl`, `api`, `apiKey`, and model ID are correct.
3. Test the provider directly:
   ```bash theme={null}
   curl https://api.anthropic.com/v1/messages \
     -H "x-api-key: YOUR_API_KEY" \
     -H "content-type: application/json" \
     -d '{"model":"claude-sonnet-4-20250514","max_tokens":10,"messages":[{"role":"user","content":"hi"}]}'
   ```
4. For OpenAI-compatible providers, confirm `baseUrl` is correct and reachable from the machine running Siclaw.

## kubectl Permission Denied

**Symptom**: "Error from server (Forbidden)" during investigation.

Siclaw uses a kubeconfig imported into its credential store. Verify:

```bash theme={null}
# See whether Siclaw has imported credentials
ls .siclaw/credentials/manifest.json
```

If no kubeconfig has been imported yet:

* TUI: run `/setup`
* Local Server: open **Credentials** in the Web UI

Then verify the same kubeconfig can read your cluster:

```bash theme={null}
kubectl --kubeconfig /path/to/imported.kubeconfig get pods --all-namespaces
```

Siclaw needs read-oriented access. A typical minimum RBAC baseline is:

```yaml theme={null}
rules:
  - apiGroups: ["", "apps", "batch", "events.k8s.io"]
    resources: ["*"]
    verbs: ["get", "list", "watch"]
  - apiGroups: [""]
    resources: ["pods/log", "pods/exec"]
    verbs: ["get", "create"]
```

## Memory Search Not Working

**Symptom**: `memory_search` tool not available, or "embedding provider not configured".

Investigation Memory semantic search requires an embedding provider. Add to `.siclaw/config/settings.json`:

```json theme={null}
{
  "embedding": {
    "baseUrl": "https://api.example.com/v1",
    "apiKey": "sk-...",
    "model": "bge-m3",
    "dimensions": 1024
  }
}
```

Without this, all other features work normally — only semantic memory search is disabled.

## Port Conflicts

**Symptom**: "EADDRINUSE" when starting Gateway.

```bash theme={null}
# Check what's using the port
lsof -i :3000
```

Current Gateway builds listen on `3000` by default. Stop the conflicting process, then start Siclaw again.

## SQLite Lock Error

**Symptom**: "Database is locked" or "Another instance is already running".

Only one Siclaw process can use the same SQLite database at a time. Check for existing processes:

```bash theme={null}
ps aux | grep siclaw
# Kill stale processes if needed
```

The default lockfile is:

```text theme={null}
.siclaw/data.sqlite.lock
```

This path is relative to the directory where you started Siclaw.

## Skill Script Rejected

**Symptom**: Script stuck in "pending" or "rejected" status.

Skill scripts go through a 3-step review:

1. **Static analysis** — 27 danger patterns checked (e.g., `rm -rf`, `chmod 777`, `curl | sh`)
2. **AI review** — LLM checks for destructive operations
3. **Human approval** — a `skill_reviewer` must approve

If rejected, check the rejection reason in the Web UI and modify the script to be read-only.

## Getting Help

* [GitHub Issues](https://github.com/scitix/siclaw/issues) — bug reports and feature requests
* [Slack Community](https://join.slack.com/t/siclaw-scitix/shared_invite/zt-3rrsoc2ic-JIfbfvT1_04sqgQorSRfmw) — questions and discussion