DenchClaw Troubleshooting: Common Issues and Fixes

DenchClaw works out of the box for most users. When it doesn't, the issues tend to be one of a handful of well-understood problems: the gateway won't start, Telegram isn't connecting, the database seems corrupt, a specific query returns unexpected results.

This guide covers the most common issues, their causes, and step-by-step fixes. Keep this bookmarked for the next time something goes sideways.

Diagnostic First Steps#

Before diving into specific issues, gather diagnostic information:

# 1. Check gateway status
openclaw gateway status
 
# 2. Check DenchClaw version
npx denchclaw --version
 
# 3. Check Node.js version (requires 18+)
node --version
 
# 4. Check logs (most recent 100 lines)
tail -100 ~/.openclaw-dench/workspace/.openclaw/logs/gateway.log
 
# 5. Check DuckDB file exists and isn't empty
ls -lh ~/.openclaw-dench/workspace/workspace.duckdb

Send this output to a GitHub issue or Discord if you need community help.

Issue: Gateway Won't Start#

Symptoms: openclaw gateway start hangs or exits immediately. Web UI at localhost:3100 shows "can't connect."

Fix 1: Port Already in Use#

# Check if port 19001 is occupied
lsof -i :19001
 
# If something is there, kill it or configure DenchClaw to use a different port
# Kill the occupying process:
kill -9 $(lsof -t -i:19001)
 
# Or change DenchClaw's port in .env:
echo "OPENCLAW_PORT=19002" >> ~/.openclaw-dench/workspace/.env

Fix 2: Node.js Version Too Old#

node --version  # Must be v18 or higher

If you're on an older version:

# Install nvm (Node Version Manager)
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
nvm install 22
nvm use 22

Fix 3: Corrupted Installation#

# Clear the npx cache and reinstall
npx clear-npx-cache  # If available
# Or manually:
rm -rf ~/.npm/_npx
npx denchclaw@latest

Fix 4: Missing Workspace Directory#

If the workspace doesn't exist:

mkdir -p ~/.openclaw-dench/workspace
npx denchclaw  # Reinitializes the workspace

Issue: Web UI Not Loading#

Symptoms: Gateway is running (status shows "running") but localhost:3100 shows a blank page or error.

Fix 1: Clear Browser Cache#

Hard refresh: Cmd + Shift + R (Mac) or Ctrl + Shift + R (Windows)

Or open an incognito window at localhost:3100.

Fix 2: Check the Correct Port#

DenchClaw defaults to port 3100 for the web UI. If you changed the port:

grep OPENCLAW_PORT ~/.openclaw-dench/workspace/.env

Fix 3: Firewall or Security Software#

If you're on a corporate network or have strict firewall rules:

• Try accessing 127.0.0.1:3100 instead of localhost:3100
• Temporarily disable any local proxy or VPN and try again

Issue: Database Errors#

Symptoms: "Database locked", "Unable to open database", queries returning errors, agent reporting database issues.

Fix 1: Database Lock (Another Process Has It Open)#

DuckDB can only have one writer at a time. If another process has the file open:

# Find what's holding the lock
lsof ~/.openclaw-dench/workspace/workspace.duckdb
 
# Stop the DenchClaw gateway first
openclaw gateway stop
 
# Wait a moment, then restart
openclaw gateway start

Fix 2: Corrupt DuckDB File#

If the database file is corrupted (usually from an interrupted write):

# Test if the file is readable
duckdb ~/.openclaw-dench/workspace/workspace.duckdb "SELECT 1;"
# If this fails, the file is corrupt

Recovery:

1. Stop the gateway: openclaw gateway stop
2. Restore from backup (see backup guide)
3. If no backup exists, try DuckDB's repair utility:

   Copy

   duckdb --recovery ~/.openclaw-dench/workspace/workspace.duckdb

Fix 3: Disk Full#

df -h ~  # Check available disk space

DuckDB can fail silently when disk space is exhausted. Free up space and restart the gateway.

Fix 4: PIVOT View Missing#

If a query on v_people or v_companies fails with "table not found":

# Ask the agent to regenerate views
# Or manually in DuckDB:
duckdb ~/.openclaw-dench/workspace/workspace.duckdb

Then ask the agent: "Regenerate the PIVOT views for all objects."

Issue: Telegram Not Connecting#

Symptoms: You've set up a Telegram bot but messages don't receive responses. The agent doesn't seem to see Telegram messages.

Fix 1: Bot Token Invalid or Expired#

Check if the bot token is current:

grep TELEGRAM_BOT_TOKEN ~/.openclaw-dench/workspace/.env

Test the token directly:

curl https://api.telegram.org/bot<YOUR_TOKEN>/getMe
# Should return your bot's info

If invalid, create a new token via BotFather: /revoke the old token, then /token to get a new one. Update your .env.

Fix 2: Webhook vs. Polling Conflict#

DenchClaw uses long-polling to receive Telegram messages. If a webhook is configured elsewhere for the same bot token, they'll conflict:

# Remove any existing webhook:
curl -X POST "https://api.telegram.org/bot<YOUR_TOKEN>/deleteWebhook"

Then restart the gateway: openclaw gateway restart

Fix 3: Privacy Mode Blocking Group Messages#

If your bot is in a Telegram group but not receiving messages:

In BotFather: /mybots → select your bot → Bot Settings → Group Privacy → Turn Off

Restart the gateway after changing this setting.

Fix 4: Firewall Blocking Outbound to Telegram#

On corporate networks or VPS providers with strict outbound rules, Telegram API calls may be blocked:

curl -s https://api.telegram.org/bot<YOUR_TOKEN>/getMe
# If this times out or fails, your network is blocking api.telegram.org

Solution: Use a VPN, or contact your network administrator.

Issue: Agent Gives Wrong or Incomplete Answers#

Symptoms: The agent misidentifies objects, returns empty results for queries you know should have data, or makes incorrect SQL.

Fix 1: Object Schema Out of Date#

The agent reads object schemas from .object.yaml files. If you edited the YAML directly without telling the agent, it may have stale context:

"Reload the schema for all my objects and confirm what objects and fields you can see."

Fix 2: PIVOT View Stale#

If you added new fields but they're not showing up in queries:

duckdb ~/.openclaw-dench/workspace/workspace.duckdb

Then ask the agent: "Refresh the PIVOT views for the people and company objects."

Fix 3: Clarify the Query#

Sometimes the agent needs more context:

Instead of: "Show me all my leads" Try: "Show me all entries in the people object where the Status field equals 'Lead', sorted by created date descending"

More specific queries produce more reliable results.

Issue: Browser Agent Not Working#

Symptoms: Browser automation commands fail, sites don't open, "Chrome profile not found" errors.

Fix 1: Chrome Not Installed#

The browser agent requires Chromium-based Chrome. Verify it's installed:

which google-chrome  # or google-chrome-stable

If not installed, download from google.com/chrome.

Fix 2: Chrome Profile Path Wrong#

DenchClaw tries to find your Chrome profile automatically. If it fails:

# Find your Chrome profile manually
ls ~/Library/Application\ Support/Google/Chrome/
# Look for "Default" or a profile directory like "Profile 1"
 
# Tell the agent the correct path:
# "Set the Chrome profile path to ~/Library/Application Support/Google/Chrome/Default"

Fix 3: Chrome Already Running#

The browser agent can't start a new Chrome instance if Chrome is already running with the same profile. Close Chrome or use the agent's managed profile:

# Tell the agent to use a separate automation profile, not your main Chrome profile

Issue: Performance Degradation Over Time#

Symptoms: Queries that used to be fast are now slow. The UI feels sluggish. Agent responses take longer.

Fix 1: Run Database Maintenance#

duckdb ~/.openclaw-dench/workspace/workspace.duckdb "VACUUM; ANALYZE; CHECKPOINT;"

Fix 2: Clear Old Logs#

Log files can grow large:

# Check log size
du -sh ~/.openclaw-dench/workspace/.openclaw/logs/
 
# Truncate old logs (keeps recent 10,000 lines)
for f in ~/.openclaw-dench/workspace/.openclaw/logs/*.log; do
  tail -10000 "$f" > "$f.tmp" && mv "$f.tmp" "$f"
done

Fix 3: Check for Runaway Cron Jobs#

If you've set up many scheduled tasks, some might be overlapping or running more frequently than intended:

"List all my active cron jobs and their schedules. Are any running more frequently than I intended?"

Getting More Help#

If these fixes don't resolve your issue:

1. GitHub Issues: Search for similar issues at github.com/DenchHQ/denchclaw/issues. If none match, open a new issue with your diagnostic output.

2. Discord #help: The community at discord.com/invite/clawd is active and usually responds quickly.

3. Logs: Attach the relevant section of ~/.openclaw-dench/workspace/.openclaw/logs/gateway.log to any support request.

Frequently Asked Questions#

How do I completely reset DenchClaw and start fresh?#

openclaw gateway stop
# Back up first if you want to keep your data:
cp -r ~/.openclaw-dench ~/.openclaw-dench-backup
# Then reset:
rm -rf ~/.openclaw-dench
npx denchclaw  # Reinitializes everything from scratch

DenchClaw was working yesterday and stopped working today. What changed?#

Check if your Node.js or npm was auto-updated. Check if your macOS received a security update that changed permissions. Run the diagnostic steps at the top of this guide and review the gateway logs for error messages.

Can I run DenchClaw in verbose/debug mode?#

DEBUG=openclaw:* npx denchclaw

This outputs detailed debug logging to the console. Useful for diagnosing startup issues.

Ready to try DenchClaw? Install in one command: npx denchclaw. Full setup guide →