Skip to main content

​
Node.js Version

Siclaw requires Node.js 22.12.0 or later. 
node --version
# Must be v22.12.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:
  1. Open the active config file: 
    ls .siclaw/config/settings.json
  2. Verify baseUrl, api, apiKey, and model ID are correct.
  3. 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"}]}'
  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: 
# 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:
  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