Troubleshooting

Node.js Version

Siclaw requires Node.js 22.19.0 or later.

node --version
# Must be v22.19.0+

If you’re on an older version, use nvm:

nvm install 22
nvm use 22

LLM Connection Failures

Symptom: “Failed to connect to LLM provider” or empty responses. Check:

Open the active config file:
ls .siclaw/config/settings.json
Verify baseUrl, api, apiKey, and model ID are correct.

Test the provider directly:

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"}]}'

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:

# 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:

kubectl --kubeconfig /path/to/imported.kubeconfig get pods --all-namespaces

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

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:

{
  "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.

# 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:

ps aux | grep siclaw
# Kill stale processes if needed

The default lockfile is:

.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:

Static analysis — 27 danger patterns checked (e.g., rm -rf, chmod 777, curl | sh)
AI review — LLM checks for destructive operations
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 — bug reports and feature requests
Slack Community — questions and discussion

Introduction

Quick Start

Troubleshooting

Node.js Version

LLM Connection Failures

kubectl Permission Denied

Memory Search Not Working

Port Conflicts

SQLite Lock Error

Skill Script Rejected

Getting Help

​Node.js Version

​LLM Connection Failures

​kubectl Permission Denied

​Memory Search Not Working

​Port Conflicts

​SQLite Lock Error

​Skill Script Rejected

​Getting Help

Node.js Version

LLM Connection Failures

kubectl Permission Denied

Memory Search Not Working

Port Conflicts

SQLite Lock Error

Skill Script Rejected

Getting Help