Troubleshooting

Resolve common PULSE issues

Troubleshooting

Solutions for common PULSE problems.

Deployment Issues

”Database not found” Error

Error: Database not found: pulse_analytics

Solution:

1. Check database exists:

   wrangler d1 list

2. Verify wrangler.toml has correct database_id:

   [[d1_databases]]
   binding = "DB"
   database_id = "YOUR_DATABASE_ID"

3. If still failing, recreate:

   wrangler d1 create pulse_analytics

“Unauthorized” After Deploy

Error: 401 Unauthorized

Solution:

1. Verify API secret is set:

   wrangler secret list --env production

2. If missing, set it:

   wrangler secret put API_SECRET --env production

3. Re-deploy:

   npm run deploy:blue

Event Ingestion Issues

Events Not Being Recorded

Check:

1. API authentication:

   curl https://api.example.com/api/v1/auth \
     -H "Authorization: Bearer YOUR_API_KEY"

2. Event payload is valid:

   curl -X POST https://api.example.com/collect \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"site_id":"site_abc123","event_type":"test","timestamp":'$(date +%s000)',"session_id":"test"}'

3. Check database is accessible:

   curl https://api.example.com/health/ready

Rate Limiting Errors

{
  "success": false,
  "error": "Rate limit exceeded"
}

Solution:

1. Wait 60 seconds and retry
2. Batch events together
3. Increase rate limit in wrangler.toml

Query Issues

”Site not found” in Queries

Solution:

1. Verify site_id exists:

   # Send test event to create site implicitly
   curl -X POST https://api.example.com/collect \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -d '{"site_id":"site_abc123",...}'

2. Use same site_id in queries:

   curl "https://api.example.com/api/v1/stats?site_id=site_abc123&metric=event_count" \
     -H "Authorization: Bearer YOUR_API_KEY"

Queries Return No Data

Check:

1. Wait 5-10 seconds for event processing
2. Verify events were sent
3. Check time range includes events
4. Verify event timestamps are in milliseconds

Performance Issues

High API Latency

Error: Request timeout (>30 seconds)

Solutions:

1. Check KV cache hit rate:

   • Target: >80%
   • If <80%: Increase TTL or cache more queries

2. Check database load:

   • Verify indexes exist
   • Analyze slow queries

3. Reduce query complexity:

   • Smaller date ranges
   • Fewer aggregations
   • More specific filters

WebSocket Disconnections

Check:

1. Browser console for error messages

2. Verify WebSocket upgrade succeeds:

   curl -i -N -H "Connection: Upgrade" \
     -H "Upgrade: websocket" \
     https://api.example.com/api/v1/stats/stream

3. Check Cloudflare timeout (30s idle)

Database Issues

D1 Connection Errors

Error: D1 database connection failed

Solution:

1. Verify database binding in wrangler.toml
2. Check D1 status in Cloudflare dashboard
3. Restart worker:

   npm run deploy:blue

Migration Failures

Error: Migration 022 failed: syntax error

Solution:

1. Check migration SQL is valid:

   sqlite3 db.sqlite < migrations/022.sql

2. Review migration for dialect issues

3. Rollback if needed:

   npm run deploy:rollback

Monitoring Issues

Datadog Not Receiving Metrics

Check:

1. Verify API key is set:

   wrangler secret list --env production

2. Check environment variable:

   [vars]
   DATADOG_SITE = "datadoghq.com"

3. Verify metrics are being generated:

   wrangler tail  # Check logs for metrics

Support

If issues persist:

1. Check Logs:

   wrangler tail --env production

2. Review Cloudflare Status:

   • https://www.cloudflarestatus.com

3. Community Support:

   • GitHub Issues: https://github.com/tesorosocial/pulse/issues

Next Steps

• Compliance — GDPR and compliance
• Monitoring — Set up observability