Skip to content

Troubleshooting

Jump to bottom
dev-mondoshawan edited this page Apr 24, 2026 · 1 revision

Troubleshooting

This guide covers common issues you may encounter when running ScarpShield and how to resolve them.

Cannot Connect to Chain

Symptom:

ERROR: Failed to connect to Ethereum RPC
ERROR: Connection timeout after 30 seconds

Diagnosis: The RPC endpoint is unreachable, rate-limiting your requests, or returning errors.

Solutions:

  1. Verify the RPC URL

    curl -X POST https://eth.llamarpc.com \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'

    You should receive a JSON response with a hex block number.

  2. Try an alternative public RPC

    • Ethereum: https://rpc.ankr.com/eth, https://cloudflare-eth.com
    • Polygon: https://polygon-rpc.com
    • BSC: https://bsc-dataseed.binance.org

  3. Switch to a dedicated provider

  4. Check your network — Ensure your machine has internet access and no firewall is blocking outbound HTTPS on port 443.

No Alerts Received

Symptom: Events are detected in the logs, but no alerts arrive on external channels.

Diagnosis: Alert channels may be misconfigured, disabled, or failing silently.

Solutions:

  1. Check enabled channels

    python main.py alerts

    Verify that your target channel shows enabled: true.

  2. Run the test command

    python main.py test-alerts

    This sends a test message to every enabled channel and reports success/failure per channel.

  3. Verify credentials — Double-check API tokens, webhook URLs, and passwords. A single typo will cause silent failures.

  4. Check console output — Console alerts are always enabled. If you see alerts in the terminal but nowhere else, the issue is isolated to the external channel.

Email Not Sending

Symptom: python main.py test-alerts reports email failure.

Common Causes and Fixes:

Cause Fix
Using Google password instead of App Password Enable 2FA and generate an App Password at https://myaccount.google.com/apppasswords
Wrong port Use 587 for TLS (STARTTLS) or 465 for SSL
Wrong host Gmail = smtp.gmail.com, Outlook = smtp.office365.com
Email in spam/junk folder Add the sender address to your contacts or whitelist it
SMTP auth disabled by provider Check your email provider's documentation

Test SMTP manually:

telnet smtp.gmail.com 587

If the connection hangs, your network or ISP may be blocking SMTP traffic.

Discord Webhook Failing

Symptom: Discord alerts not appearing; test command reports failure.

Solutions:

  1. Verify the webhook URL — Copy it again from Server Settings → Integrations → Webhooks. It should look like:

    https://discord.com/api/webhooks/1234567890123456789/abcdefghijklmnopqrstuvwxyz

  2. Check webhook still exists — Webhooks can be deleted accidentally. Re-create if unsure.

  3. Verify permissions — The webhook must have permission to post in the target channel.

  4. Test with curl:

    curl -X POST YOUR_WEBHOOK_URL \
  -H "Content-Type: application/json" \
  -d '{"content":"ScarpShield test"}'

Slack Webhook Failing

Symptom: Slack alerts not appearing.

Solutions:

  1. Verify the webhook URL — Copy it again from your Slack app settings. It should look like:

    https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX

  2. Check app is not suspended — If the Slack app was deactivated, reactivate it at https://api.slack.com/apps

  3. Verify channel access — The app must be authorized to post in the target channel.

  4. Test with curl:

    curl -X POST YOUR_WEBHOOK_URL \
  -H "Content-Type: application/json" \
  -d '{"text":"ScarpShield test"}'

Telegram Not Working

Symptom: No Telegram messages; test command reports failure.

Solutions:

  1. Verify bot token — Message @BotFather and send /token to confirm. It should look like:

    123456789:ABCdefGHIjklMNOpqrSTUvwxyz

  2. Ensure bot is in the chat — Add the bot to the target group or channel as a member.

  3. Verify chat ID — Run:

    curl https://api.telegram.org/bot<TOKEN>/getUpdates

    Look for the chat.id field. Group IDs are negative numbers (e.g., -123456789).

  4. Send a message first — The bot cannot see a chat until a message has been sent in it after the bot joined.

  5. Privacy mode — In groups, ensure the bot's privacy mode is disabled (via @BotFather → Bot Settings → Group Privacy) if you want it to read all messages.

Events Missed After Restart

Symptom: After restarting ScarpShield, some events that occurred while it was offline are not alerted.

Explanation: This is normal if the state file was deleted or corrupted. ScarpShield resumes from the current block when no state is available.

Solutions:

  1. Preserve the state file — Do not delete .scarpshield_state.json. It tracks the last processed block per chain.

  2. Force a re-scan (advanced) — If you want to catch up on missed events, manually edit the state file to set the last block to an earlier number. Note that this may trigger duplicate alerts for events already processed.

  3. Check state file integrity — Ensure it is valid JSON:

    {
  "ethereum": 18912345,
  "polygon": 56789012
}

High RPC Usage

Symptom: Your RPC provider reports high request counts or rate limits you.

Solutions:

  1. Increase the poll interval

    python main.py settings --poll-interval 60

    or edit config.json:

    { "poll_interval_seconds": 60 }

  2. Reduce monitored contracts — Remove contracts that no longer need monitoring.

  3. Use a dedicated RPC provider — Free public RPCs have low limits. Upgrade to Infura, Alchemy, or QuickNode for higher quotas.

  4. Monitor fewer chains — If you only need Ethereum, remove Polygon, BSC, and other chains from monitoring.

Invalid Address Error

Symptom:

ERROR: Invalid contract address: 0x12345

Cause: The address is not a valid checksummed or lowercase Ethereum address.

Rules:

  • Must be exactly 42 characters: 0x + 40 hex characters
  • Valid: 0xA0b86a33E6441e0A421e56C5bC6a3B0A4B2B3E5f
  • Invalid: 0x12345 (too short), 0xGHIJKL... (non-hex characters), A0b86a33... (missing 0x)

Fix: Copy the full address from a block explorer (Etherscan, BscScan, etc.) and paste it exactly.

GUI Won't Start

Symptom: python main.py gui fails with an error or the browser does not open.

Solutions:

  1. Check port availability

    python main.py gui --port 8080

    The default port (8050) may be in use by another application.

  2. Verify Flask is installed

    pip install -r requirements.txt

    Ensure flask is in the installed packages list.

  3. Check for Python errors — Read the traceback carefully. Common issues include missing templates or static files.

  4. Use --no-browser — If the server starts but the browser doesn't open, access it manually:

    python main.py gui --no-browser
# Then open http://127.0.0.1:8050 in your browser

USDC / USDT Values Look Wrong

Symptom: Transfer values display as extremely large or small numbers.

Cause: Token decimals were not detected correctly.

Solutions:

  1. Check RPC connectivity — The decimals query requires a working RPC. If the RPC was down when the contract was added, ScarpShield may have fallen back to 18 decimals.

  2. Re-add the contract — Remove and re-add the contract to force a fresh decimals query:

    python main.py remove-contract <ID>
python main.py add-contract

  3. Verify the contract — Ensure the address is a standard ERC-20 contract. Non-standard tokens may not implement the decimals() function.

Expected values:

  • USDC: 6 decimals → 1,250.00 USDC
  • WBTC: 8 decimals → 2.34567890 WBTC
  • Generic token: 18 decimals → 100.0 TOKEN

Rate Limiting

Symptom: Logs show repeated 429 Too Many Requests or Rate limit exceeded errors.

Explanation: ScarpShield has built-in exponential backoff that activates automatically when rate limits are hit. The system will retry with increasing delays (5s, 10s, 20s, 40s, up to 5 minutes).

Solutions:

  1. Wait for backoff to clear — The system recovers automatically once the rate limit window resets.

  2. Switch to a paid RPC — Public endpoints have strict limits. Providers like Infura, Alchemy, and QuickNode offer much higher quotas.

  3. Reduce polling frequency — Increase poll_interval_seconds to 30-60 seconds.

  4. Monitor fewer contracts or chains — Each contract and chain adds to the total RPC call volume.

Getting More Help

If your issue is not covered here:

  1. Check the logs for detailed error messages
  2. Run with verbose output if available
  3. Open an issue on the GitHub repository with:
    • The exact error message
    • Your ScarpShield version
    • Relevant configuration (redact secrets)
    • Steps to reproduce

Clone this wiki locally