Skip to main content

​
Overview

This guide covers common issues you might encounter when running Base Audit Bot and their solutions.

​
Connection Issues

​
Bot Not Connecting to Base RPC

  • Bot fails to start with RPC connection errors
  • Logs show “Connection refused” or “Timeout” errors
  • Cannot fetch block information
1

Verify RPC URL

Check BASE_RPC_URL in .env:
BASE_RPC_URL=https://mainnet.base.org
The bot validates that the URL starts with http or https (via config.py:94).
2

Test network connectivity

# Test RPC endpoint
curl -X POST https://mainnet.base.org \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'
Expected response with block number.
3

Try alternative RPC endpoints

Alternative Base mainnet RPC URLs:
# Public endpoints
BASE_RPC_URL=https://mainnet.base.org
BASE_RPC_URL=https://base.llamarpc.com
BASE_RPC_URL=https://base.blockpi.network/v1/rpc/public
For production, consider using a dedicated RPC provider like Alchemy, Infura, or QuickNode.
4

Check firewall rules

Ensure outbound HTTPS (port 443) is allowed:
# Test outbound connection
telnet mainnet.base.org 443

​
API Issues

​
Twitter Posting Fails

  • Logs show “Twitter posting failed”
  • Authentication errors
  • Rate limit errors
1

Verify all credentials are set

The bot requires all 5 Twitter credentials (from README.md:104):
TWITTER_API_KEY=your_twitter_api_key
TWITTER_API_SECRET=your_twitter_api_secret
TWITTER_ACCESS_TOKEN=your_twitter_access_token
TWITTER_ACCESS_SECRET=your_twitter_access_secret
TWITTER_BEARER_TOKEN=your_twitter_bearer_token
Missing any credential will prevent the bot from starting (via config.py:48).
2

Check app permissions

Your Twitter app needs read and write permissions:
  1. Go to https://developer.twitter.com/
  2. Select your app
  3. Navigate to Settings > User authentication settings
  4. Ensure OAuth 1.0a is enabled
  5. Verify Read and write permissions are selected
If you changed permissions, you must regenerate access tokens.
3

Check rate limits

Twitter API has rate limits (from README.md:268):
  • Tweet posting: 300 tweets per 3 hours
  • DM reading: 15 requests per 15 minutes
The bot respects these limits automatically, but check for excessive usage.
4

Test credentials

Test Twitter authentication:
import tweepy
from config import get_config

config = get_config()
auth = tweepy.OAuthHandler(config.twitter_api_key, config.twitter_api_secret)
auth.set_access_token(config.twitter_access_token, config.twitter_access_secret)
api = tweepy.API(auth)

# Verify credentials
print(api.verify_credentials().screen_name)

​
Basescan API Errors

  • Cannot fetch verified contract source code
  • “Invalid API key” errors
  • Rate limit exceeded
1

Verify API key

BASESCAN_API_KEY=your_basescan_api_key
Get a free API key at https://basescan.org/apis
2

Check API rate limits

Free tier limits:
  • 5 requests per second
  • 100,000 requests per day
The bot handles rate limiting, but check your usage:
# Check API key status
curl "https://api.basescan.org/api?module=account&action=balance&address=0x0000000000000000000000000000000000000000&apikey=YOUR_API_KEY"
3

Increase delays between requests

If hitting rate limits, adjust scan settings:
SCAN_INTERVAL_MINUTES=30  # Increase from 15
BLOCKS_TO_SCAN=50         # Decrease from 100

​
Anthropic API Errors

  • Audits not running
  • “Invalid API key” errors
  • Rate limit or quota exceeded
1

Verify API key

ANTHROPIC_API_KEY=sk-ant-api03-...
Get an API key at https://console.anthropic.com/
2

Check account credits

Log into Anthropic console and verify:
  • API key is active
  • Account has credits
  • No rate limit restrictions
3

Monitor usage

Check Claude API usage in Anthropic console.Large contracts consume more tokens. Consider:
  • Increasing MIN_CONTRACT_SIZE to filter small contracts
  • Reducing audit frequency

​
Audit Issues

​
Audits Not Running

  • Contracts detected but not audited
  • “Skipping audit” messages in logs
  • No audit results
1

Check contract has verified source

Only contracts with verified source code on Basescan can be audited (from README.md:269).Verify on Basescan:
https://basescan.org/address/0x...
Look for green checkmark indicating verified contract.
2

Check contract size

Contracts smaller than MIN_CONTRACT_SIZE are skipped:
MIN_CONTRACT_SIZE=100  # bytes
This filters out very small contracts that are unlikely to be interesting.
3

Check for blocklist

Contract might be in blocklist table:
sqlite3 data/bot.db "SELECT * FROM blocklist"
Remove if needed:
sqlite3 data/bot.db "DELETE FROM blocklist WHERE address='0x...'"
4

Check logs for errors

# Docker
docker-compose logs | grep -i audit

# Python
tail -f logs/bot.log | grep -i audit
Look for specific error messages (from README.md:293).

​
GitHub Repository Not Found

  • Cannot find GitHub repository for contract
  • “No repository found” messages
Contract source on Basescan might not include GitHub links.The bot searches for:
  • GitHub URLs in contract comments
  • Repository links in verified source metadata
  • Organization/repository patterns
Not all verified contracts have associated GitHub repositories. This is expected behavior.

​
Webhook Issues

​
Webhook Not Receiving Events

  • No webhook events in logs
  • GitHub shows delivery failures
  • No tweets about repository updates
1

Verify webhook URL is accessible

Test from external location:
curl https://your-domain.com/webhook/github
Should return 405 (Method Not Allowed) for GET requests.
2

Check webhook secret matches

Verify WEBHOOK_SECRET in .env matches GitHub webhook configuration (from README.md:298).
Signature verification failures are logged as “Invalid webhook signature” (via webhook.py:72).
3

Verify GitHub webhook configuration

In GitHub repository settings:
  1. Go to Settings > Webhooks
  2. Click on your webhook
  3. Check Recent Deliveries
  4. Look for errors or failed deliveries
Common issues:
  • SSL certificate errors
  • Connection timeouts
  • HTTP errors (4xx, 5xx)
4

Check firewall and port

Ensure port 5000 is accessible:
# Check if port is open
netstat -tuln | grep 5000

# Check firewall
sudo ufw status | grep 5000
5

Test with ngrok (development)

For local testing:
ngrok http 5000
Use the ngrok URL in GitHub webhook configuration.

​
Signature Verification Failing

  • Logs show “Invalid webhook signature”
  • GitHub deliveries succeed but bot rejects them
1

Verify secret matches exactly

Check for:
  • Extra whitespace
  • Trailing newlines
  • Copy/paste errors
# Check secret in environment
docker-compose exec audit-bot env | grep WEBHOOK_SECRET
2

Check reverse proxy configuration

If using nginx/Apache, ensure headers are forwarded:
proxy_set_header X-Hub-Signature-256 $http_x_hub_signature_256;
3

Test signature manually

import hmac
import hashlib

secret = "your_webhook_secret"
payload = b'{"test":true}'

signature = "sha256=" + hmac.new(
    secret.encode(),
    payload,
    hashlib.sha256
).hexdigest()

print(signature)

​
Docker Issues

​
Container Exits Immediately

  • Container starts then exits
  • docker-compose ps shows “Exit 1”
1

Check logs for errors

docker-compose logs
Common errors:
  • Missing environment variables (from config.py:58)
  • Invalid configuration values (from config.py:92)
  • Permission denied errors
2

Verify .env file exists

ls -la .env
If missing:
cp .env.example .env
nano .env
3

Check environment variables loaded

docker-compose config
Verify all required variables are set.

​
Health Check Failing

  • Container status shows “unhealthy”
  • Health check endpoint not responding
1

Check webhook server is running

docker-compose exec audit-bot ps aux | grep python
2

Test health endpoint internally

docker-compose exec audit-bot curl http://localhost:5000/health
Should return:
{"status": "healthy", "timestamp": "..."}
3

Check logs for startup errors

docker-compose logs --tail=50
4

Verify port binding

docker-compose exec audit-bot netstat -tuln | grep 5000

​
Volume Permission Issues

  • “Permission denied” errors
  • Cannot write to database
  • Log file errors
1

Create directories with proper permissions

mkdir -p data logs
chmod 755 data logs
2

Check ownership

ls -la data logs
If needed, adjust ownership:
sudo chown -R $USER:$USER data logs
3

Run container as specific user

Add to docker-compose.yml:
services:
  audit-bot:
    user: "1000:1000"  # Your user:group ID

​
Database Issues

​
Database Locked

  • “Database is locked” errors
  • Write operations failing
1

Check for multiple bot instances

ps aux | grep bot.py
docker ps | grep audit-bot
Stop duplicate instances.
2

Check for stale locks

# Check for SQLite lock files
ls -la data/bot.db*
Remove if bot is not running:
rm data/bot.db-shm data/bot.db-wal
3

Restart the bot

docker-compose restart

​
Database Corruption

  • “Database disk image is malformed” errors
  • Query failures
1

Check database integrity

sqlite3 data/bot.db "PRAGMA integrity_check;"
2

Restore from backup

cp data/bot.db data/bot.db.corrupted
cp data/bot.db.backup data/bot.db
3

Rebuild database

If no backup:
mv data/bot.db data/bot.db.old
# Bot will create new database on startup
docker-compose restart

​
Configuration Issues

​
Missing Required Environment Variables

  • Bot fails to start
  • “Missing required environment variables” error
The bot requires these variables (from config.py:48):
BASE_RPC_URL
BASESCAN_API_KEY
ANTHROPIC_API_KEY
TWITTER_API_KEY
TWITTER_API_SECRET
TWITTER_ACCESS_TOKEN
TWITTER_ACCESS_SECRET
1

Check .env file

cat .env | grep -E "(BASE_RPC_URL|BASESCAN_API_KEY|ANTHROPIC_API_KEY|TWITTER)"
2

Verify values are set

Look for empty values:
grep "=your_" .env
Replace all placeholder values with actual API keys.

​
Invalid Configuration Values

  • Bot exits with validation errors
  • “ValueError” in logs
The bot validates configuration on startup (via config.py:92):
1

Check BASE_RPC_URL format

Must start with http or https:
BASE_RPC_URL=https://mainnet.base.org  # ✓ Valid
BASE_RPC_URL=mainnet.base.org          # ✗ Invalid
2

Check numeric values

Must be positive integers:
SCAN_INTERVAL_MINUTES=15  # Must be >= 1
BLOCKS_TO_SCAN=100        # Must be >= 1
3

Check port number

WEBHOOK_PORT=5000  # Valid port number

​
Performance Issues

​
High Memory Usage

  • Container using excessive RAM
  • System slowdown
1

Monitor memory usage

docker stats base-audit-bot
2

Clear temp repos

docker-compose exec audit-bot rm -rf /app/temp_repos/*
3

Set memory limits

Add to docker-compose.yml:
services:
  audit-bot:
    deploy:
      resources:
        limits:
          memory: 1G

​
High Disk Usage

  • Disk space filling up
  • Large database or log files
1

Check disk usage

du -sh data logs
docker system df
2

Clean old logs

Log rotation is automatic (10MB, 3 files) via docker-compose.yml:44, but you can manually clean:
docker-compose down
rm logs/*
docker-compose up -d
3

Vacuum database

sqlite3 data/bot.db "VACUUM;"
4

Clean Docker system

docker system prune -a

​
Getting Help

Check Logs

Always check logs first:
docker-compose logs -f

Enable Debug Logging

Set in .env:
LOG_LEVEL=DEBUG

Test Configuration

Validate config:
docker-compose config

Check Health

Test health endpoint:
curl http://localhost:5000/health
If you’re still having issues after trying these solutions, check the source code for specific error handling:
  • Configuration: config.py:44
  • RPC connection: scanner.py
  • Webhook server: webhook.py:15
  • Database: models.py

Build docs developers (and LLMs) love

Get started for freeTalk to us