Skip to main content

Troubleshooting

Common issues and solutions for BlackTide. Find quick fixes for alerts, monitors, integrations, and API problems.

Alerts Not Arriving

Problem

You configured an alert rule but aren't receiving notifications when monitors fail.

Possible Causes

  • Alert rule is disabled
  • Alert channel is misconfigured
  • Monitor is silenced
  • Failure threshold not met
  • Alert channel is disabled

Solution

  1. Check Alert Rule Status
    • Go to Alerts → Alert Rules
    • Verify rule is Enabled
    • Check rule applies to correct monitors
  2. Test Alert Channel
    • Go to Alerts → Alert Channels
    • Click Test on the channel
    • Verify test notification arrives
  3. Check Monitor Silence
    • Look for 🔇 icon on monitor
    • Unsilence if needed
  4. Verify Failure Threshold
    • Rule: "3 consecutive failures"
    • Monitor failed only 2 times → no alert yet
    • Wait for 3rd failure or adjust threshold

Monitor Showing False Positives

Problem

Monitor reports failures even though service is actually up.

Possible Causes

  • Timeout too short
  • Expected status code incorrect
  • Network issues from monitoring location
  • SSL certificate validation failing

Solution

  1. Increase Timeout
    Current: 10 seconds
Try: 30 seconds

Edit monitor → Timeout: 30
  2. Check Expected Status
    Expected: 200
Actual: 301 (redirect)

Fix: Change expected status to 301
Or: Follow redirects option
  3. Test from Multiple Locations
    • Add check locations: US-East, EU-West, Asia
    • Require 2+ failures before alert
  4. Disable SSL Verification (not recommended)
    Only for self-signed certificates:
Edit monitor → Advanced → Skip SSL verification

Slack Notifications Not Working

Problem

Slack integration configured but messages not appearing in channel.

Possible Causes

  • Webhook URL incorrect
  • Slack app permissions changed
  • Channel deleted or renamed
  • Webhook expired or revoked

Solution

  1. Test Webhook Manually
    curl -X POST https://hooks.slack.com/services/YOUR/WEBHOOK/URL \
  -H 'Content-Type: application/json' \
  -d '{"text": "Test from BlackTide"}'

If this fails → webhook is invalid
If succeeds → BlackTide config issue
  2. Regenerate Webhook
    • Go to Slack → Apps → Incoming Webhooks
    • Delete old webhook
    • Create new webhook
    • Update BlackTide with new URL
  3. Check Channel Permissions
    • Ensure webhook app has access to channel
    • Invite app to private channels if needed

High Latency Monitors

Problem

Monitor shows high response times (2-5s) but manual testing shows fast response (<200ms).

Possible Causes

  • Cold starts (serverless functions)
  • Geographic distance to check location
  • DNS resolution included in timing
  • SSL handshake overhead

Solution

  1. Choose Closer Check Location
    • If server in US-East, use US-East check location
    • Avoid cross-continent checks unless testing CDN
  2. Warm Up Serverless
    • Increase check frequency (60s → 300s)
    • Use CloudWatch Events to keep warm
    • Or: Provision minimum capacity
  3. Review Timing Breakdown
    Total: 2.5s
  DNS: 0.5s (slow DNS)
  Connect: 0.3s
  TLS: 0.7s (slow SSL)
  Response: 1.0s (actual app)

API Returns 401 Unauthorized

Problem

API requests fail with 401 Unauthorized error.

Possible Causes

  • API token invalid or expired
  • Missing Authorization header
  • Token lacks required permissions

Solution

  1. Verify Token Format
    Correct:
Authorization: Bearer btk_abc123...

Incorrect:
Authorization: btk_abc123... (missing "Bearer")
Authorization: Bearer YOUR_API_TOKEN (placeholder not replaced)
  2. Test Token
    curl https://api.blacktide.xyz/v1/me \
  -H "Authorization: Bearer YOUR_TOKEN"

Success: Returns user info
Failure: 401 → token invalid
  3. Regenerate Token
    • Go to Settings → API Tokens
    • Click Revoke on old token
    • Click Create Token
    • Copy new token immediately

Status Page Shows "Under Maintenance"

Problem

Status page component stuck in "Under Maintenance" status.

Possible Causes

  • Monitor is paused
  • Component status manually set
  • Maintenance window not expired

Solution

  1. Resume Monitor
    • Go to Monitors
    • Find paused monitor
    • Click Resume
  2. Update Component Status
    • Go to Status Pages → Components
    • Click component
    • Change status to Operational

Web3 Gas Price Shows 0.0 Gwei

Problem

Gas price monitor shows 0.0 Gwei for Ethereum or other chains.

Possible Causes

  • RPC endpoint down or rate limited
  • Chain not supported
  • API response format changed

Solution

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

Success: Returns hex gas price
Failure: Change to different RPC
  2. Use Fallback RPC
    • Ethereum: https://rpc.ankr.com/eth
    • Polygon: https://polygon-rpc.com
    • BSC: https://bsc-dataseed.binance.org

Database Connection Errors

Problem

Backend services fail with database connection errors.

Possible Causes

  • PostgreSQL not running
  • Connection pool exhausted
  • Wrong database credentials

Solution

  1. Check PostgreSQL Status
    docker ps | grep postgres

# If not running:
cd backend
docker-compose up -d postgres
  2. Test Connection
    psql -h localhost -U blacktide -d blacktide_db

Success: PostgreSQL prompt appears
Failure: Check credentials in .env

Getting Help

If none of these solutions work:

  1. Check FAQ for more answers
  2. Search GitHub Issues
  3. Contact support: support@blacktide.xyz
  4. Join Discord: discord.gg/blacktide

Next Steps