Troubleshooting

Common issues and their solutions, organized by category. For detailed error output, open the dashboard Logs page — every worker, processor, and channel adapter writes structured logs there in real time.

Common Issues

Redis

Connection refused

Redis is not running or is not reachable at the configured address. ScalyClaw cannot start without a Redis connection.

bash

# Check if Redis is running
redis-cli ping
# Should respond: PONG

# Start Redis (macOS with Homebrew)
brew services start redis

# Start Redis (Linux with systemd)
sudo systemctl start redis

# Start Redis manually (foreground, default port)
redis-server

# Verify ScalyClaw can reach it
redis-cli -u "$REDIS_URL" ping

Make sure REDIS_URL in your environment matches where Redis is actually listening. The default is redis://127.0.0.1:6379.

NOAUTH — Authentication required

Your Redis instance requires a password but the connection URL does not include one. Any command sent without auth is rejected with NOAUTH Authentication required.

bash

# Include the password in the connection URL
export REDIS_URL="redis://:yourpassword@127.0.0.1:6379"

# With a username (Redis 6+ ACLs)
export REDIS_URL="redis://scalyclaw:yourpassword@127.0.0.1:6379"

# Test the authenticated connection
redis-cli -u "$REDIS_URL" ping

Store REDIS_URL as a secret

Once ScalyClaw is running, you can store REDIS_URL in your process environment or a .env file. The initial connection is required to boot — after that, all other secrets are pulled from Redis at runtime.

Memory limit exceeded

Redis has hit its maxmemory limit and is refusing write operations. This can cause BullMQ jobs to fail to enqueue and session state writes to error.

bash

# Check current memory usage and limit
redis-cli info memory | grep -E "used_memory_human|maxmemory"

# Set a higher limit (runtime — resets on restart)
redis-cli config set maxmemory 512mb

# Set a safe eviction policy so Redis evicts expired keys first
redis-cli config set maxmemory-policy allkeys-lru

For a permanent fix, set maxmemory and maxmemory-policy in your redis.conf. ScalyClaw's queues use TTL-aware keys for completed jobs, so an LRU eviction policy is safe for most deployments.

Channels

Bot not responding

Messages arrive but the bot sends no reply. Check each of the following in order:

Open the dashboard Channels page and confirm the channel is enabled.
Verify the token or credentials are correct. An expired or revoked token silently stops message delivery on some platforms.
Check the dashboard Logs page for errors from the channel adapter. Look for authentication errors, missing permissions, or deserialization failures.
Confirm the worker is running — a stopped worker means queued jobs are never processed. See Workers below.

Check the Jobs page

The dashboard Jobs page shows every BullMQ job and its status. If jobs are piling up in waiting without moving to active, the worker is not processing them. If jobs are in failed, expand them to read the error stack trace.

Webhook errors

Platforms that push events via webhook require a publicly reachable HTTPS URL. Common failure modes:

URL not reachable — The platform cannot connect to your server. Ensure your host and port are publicly accessible, or use a tunnel during development.
SSL certificate errors — Most platforms reject self-signed certificates. Use a certificate from Let's Encrypt or a trusted CA, or configure your reverse proxy (nginx, Caddy) to terminate TLS.
Wrong path — Confirm the webhook URL registered with the platform matches the route ScalyClaw listens on.

bash

# Expose a local port for webhook development with ngrok
ngrok http 3000

# ngrok prints a public HTTPS URL, e.g.:
# Forwarding  https://abc123.ngrok.io -> http://localhost:3000
# Use that URL as the webhook base in the dashboard Channel settings

Use ngrok for local development

ngrok provides a stable HTTPS tunnel to your local machine. Run ngrok http 3000 (adjust the port to match your ScalyClaw server), then paste the generated https:// URL into the channel webhook field. The URL changes each time you restart ngrok unless you use a paid static domain.

Message not delivered

A message was received and processed but the reply never reached the user. This is often caused by a stuck session state or a stale entry in the pending message queue.

bash

# Inspect the pending queue for a channel
redis-cli lrange "scalyclaw:pending:CHANNEL_ID" 0 -1

# Inspect the session state for a channel
redis-cli hgetall "scalyclaw:session:CHANNEL_ID"

# Reset a stuck session state (replaces CHANNEL_ID with your channel ID)
redis-cli del "scalyclaw:session:CHANNEL_ID"

# Clear the pending queue for a channel
redis-cli del "scalyclaw:pending:CHANNEL_ID"

Deleting session state drops context

Deleting a session key resets that channel to the idle state and discards any in-flight processing context. Any message that was being assembled or held in the pending queue is abandoned. Use this only when the session is clearly stuck and you are prepared to lose the in-progress exchange.

Workers

No workers connected

The dashboard shows zero active workers, or the Jobs page shows jobs sitting in waiting indefinitely. Either the worker process was never started or it cannot connect to Redis.

bash

# Start the worker from the project root
bun run worker

# Or with an explicit Redis URL
REDIS_URL="redis://127.0.0.1:6379" bun run worker

# Confirm the worker can reach Redis before starting
redis-cli -u "$REDIS_URL" ping

If the worker starts but immediately exits, check the terminal output and the dashboard Logs page for a connection error or a missing environment variable.

Jobs stuck in waiting

Jobs are enqueued but never move to active. The worker may have crashed after the last restart, or all concurrency slots are occupied by long-running jobs.

bash

# Restart the worker
bun run worker

# Check how many jobs are active vs waiting in each queue
redis-cli llen "bull:messages:active"
redis-cli llen "bull:messages:wait"
redis-cli llen "bull:tools:active"
redis-cli llen "bull:tools:wait"

If the active count equals the configured concurrency limit, the worker is saturated. Either increase the concurrency setting in the dashboard under Settings → Workers, add another worker process, or investigate why active jobs are not completing.

Code execution timeout

A skill invocation fails with a timeout error. The skill's code is taking longer than the configured maximum execution time.

bash

# Check the failed job for the timeout error in BullMQ
redis-cli lrange "bull:tools:failed" 0 4

# Run the skill manually to profile it
bun run /path/to/skill/index.ts

To resolve a timeout: increase the skill timeout via the dashboard Skills editor (set a higher timeout in the skill definition), or optimize the skill code to complete faster. Common causes include slow external API calls without timeouts, large data processing in a single pass, or missing await on async operations.

Models

API key invalid

The LLM provider rejects the request with a 401 or 403 error. The API key stored in the vault may be incorrect, expired, or copied with extra whitespace.

bash

# Retrieve the stored secret value to verify it
redis-cli get "scalyclaw:secret:ANTHROPIC_API_KEY"

# Test the key directly with the provider (Anthropic example)
curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-haiku-4-5","max_tokens":10,"messages":[{"role":"user","content":"ping"}]}'

# Update the secret in Redis with the correct key
redis-cli set "scalyclaw:secret:ANTHROPIC_API_KEY" "sk-ant-..."

After updating a secret in Redis, no restart is needed — the vault resolves secrets at runtime on each invocation.

Rate limit exceeded

The provider returns 429 errors. You have exceeded the provider's request-per-minute or token-per-minute limits for your tier.

bash

# Check current token usage in the dashboard, or query Redis directly
redis-cli get "scalyclaw:usage:today"

To reduce rate limit pressure:

Configure a fallback model in the dashboard Models page. ScalyClaw will route requests to the fallback when the primary model is rate-limited or unavailable.
Adjust per-model rate limit settings to stay within your provider quota.
Switch to a lower-tier model for non-critical tasks by assigning a cheaper model to specific agents or skills.

Budget exceeded

ScalyClaw has hit the configured spend limit and is blocking new LLM requests. In hard mode, all requests are refused until the budget resets. In soft mode, a warning is logged but requests continue.

bash

# Check the current spend against the budget limit
redis-cli get "scalyclaw:budget:spend"

# Temporarily switch to soft mode via the dashboard config, or directly:
redis-cli json.set "scalyclaw:config" "$.models.budget.mode" '"soft"'

# Reset the spend counter manually (use with care)
redis-cli set "scalyclaw:budget:spend" "0"

Soft mode allows unlimited spending

Switching to soft budget mode removes the hard spending ceiling. Use it only as a temporary measure while you raise your budget limit — do not leave it enabled permanently in production.

FAQ

Can I use local LLMs?

Yes. Any model that exposes an OpenAI-compatible API endpoint works with ScalyClaw. Ollama is the most common choice — run ollama serve, then add a model in the dashboard Models page pointing to http://localhost:11434/v1 as the base URL and set the model ID to the Ollama model name (e.g. llama3.2). No API key is required for local endpoints.

Where is data stored?

All persistent data lives in two places: a SQLite file (memory, conversation history, vector embeddings) and Redis (configuration, secrets, session state, BullMQ queues). There is no external database to provision or manage. The SQLite file path is set via the SQLITE_PATH environment variable; Redis is configured via REDIS_URL.

How do I back up my data?

Back up both the SQLite file and the Redis dataset.

bash

# Back up the SQLite memory database (stop writes first for consistency)
cp /path/to/scalyclaw.db /backups/scalyclaw-$(date +%Y%m%d).db

# Or use SQLite's built-in online backup (safe while running)
sqlite3 /path/to/scalyclaw.db ".backup /backups/scalyclaw-$(date +%Y%m%d).db"

# Trigger a Redis RDB snapshot and copy it
redis-cli bgsave
redis-cli lastsave
cp /var/lib/redis/dump.rdb /backups/redis-$(date +%Y%m%d).rdb

# Or export all keys as commands for a portable backup
redis-cli --rdb /backups/redis-$(date +%Y%m%d).rdb

For secrets specifically, note that they are stored in Redis under scalyclaw:secret:*. A full Redis backup captures them. If you only need to migrate secrets, export them individually and re-import via the dashboard Vault page or with redis-cli set.

Can I run multiple nodes?

No. ScalyClaw is designed to run as a single orchestrator node. The per-channel session state machine and pending message queue are designed around a single writer, and running two orchestrator instances against the same Redis would cause race conditions in session state. To scale throughput, add more worker processes instead — workers are stateless and safe to run in parallel. Multiple workers share the same BullMQ queues and distribute job processing without any coordination issues.

How much disk space does it need?

Very little. The SQLite memory database grows slowly — roughly 1 MB per 10,000 stored memories including vector embeddings. Redis is in-memory and its footprint depends on queue depth and the number of active sessions, but a typical idle instance uses well under 50 MB. The ScalyClaw codebase itself (including dependencies) is under 200 MB after bun install.

Is it production-ready?

Yes, with proper Redis hardening. ScalyClaw itself is stable for production use. The critical requirement is that your Redis instance is secured: enable authentication (requirepass), use TLS for any connections that cross a network boundary, bind Redis to a private interface only, configure ACLs to restrict what the ScalyClaw service account can do, and enable Redis persistence (appendonly yes or scheduled BGSAVE) so queued jobs and session state survive a Redis restart. See the Security page for additional guidance.

Can I contribute?

Yes. ScalyClaw is open-source. Visit the GitHub repository to browse the code, open issues, or submit pull requests. Contributions of all sizes are welcome — bug fixes, documentation improvements, new channel adapters, and skill ideas.