Troubleshooting Guide

Solutions to common issues and debugging techniques for Pushy.

Common Issues

Installation Fails

Error: "permission denied to create database"

PostgreSQL is not running or wrong credentials.

Solution

# Make sure PostgreSQL is running
docker-compose ps postgres
# If not running, start it
docker-compose up -d postgres
sleep 10
# Then try database operations
sqlx database create

Error: "Cannot start service postgres: driver failed programming external connectivity"

Port 5432 is already in use by another service.

Solution

# For local development - find what's using port 5432
sudo lsof -i :5432
# Kill the process (replace PID with actual process ID)
sudo kill -9 PID
# Or change the port in docker-compose.yml
ports:
  - "5433:5432"  # Use 5433 instead
# For EKS - check RDS connectivity
kubectl exec -it deployment/pushy-api -n pushy -- nc -zv your-rds-endpoint.sa-east-1.rds.amazonaws.com 5432

API Connection Errors

Error: "Connection refused" or "ECONNREFUSED"

The API server is not running or not accessible.

Debug Steps

# For EKS deployment, check pod status
kubectl get pods -n pushy
# Check pod logs
kubectl logs -n pushy -l app=pushy-api
# Test EKS endpoint
curl http://a9a18d9bb21ed4e6e9b07bbd4b8d9f16-251019334.sa-east-1.elb.amazonaws.com/health
# For local development
docker-compose logs api

Redis/ElastiCache Issues

Redis Connection Timeouts

Important: Redis is now optional in Pushy

If Redis/ElastiCache connection fails, Pushy automatically falls back to direct Contentful API calls.

Redis Connection Debugging

# Check Redis configuration
kubectl describe configmap pushy-config -n pushy | grep -i redis
# View Redis connection logs
kubectl logs -n pushy -l app=pushy-api | grep -E "Redis|redis"
# Test ElastiCache connectivity
kubectl exec -it deployment/pushy-api -n pushy -- \
  timeout 2 redis-cli -h your-redis.sa-east-1.cache.amazonaws.com ping
# If timeouts occur, check security groups in AWS Console

Database Errors

Database Connection Issues

Error: "database does not exist"

Create Database Manually

# Connect as postgres user
psql -U postgres -h localhost
# In psql:
CREATE DATABASE pushy OWNER pushy;
\q
# Run migrations
sqlx migrate run

Error: "FATAL: password authentication failed"

Wrong database password or user doesn't exist.

Reset Database User

# Connect to postgres
docker exec -it pushy-postgres-1 psql -U postgres
# Reset password
ALTER USER pushy WITH PASSWORD 'pushy';
# Grant permissions
GRANT ALL PRIVILEGES ON DATABASE pushy TO pushy;
\q

Migration Problems

Error: "relation already exists" during migration

Reset Migrations

# Drop and recreate database
sqlx database drop
sqlx database create
# Run migrations fresh
sqlx migrate run
# Or force a specific migration
sqlx migrate run --target-version 20240101000000

Docker Issues

Container Problems

Containers keep restarting

Debug Container Issues

# Check container status
docker-compose ps
# View logs for specific service
docker-compose logs -f postgres
docker-compose logs -f redis
# Inspect container
docker inspect pushy-api-1
# Reset everything
docker-compose down -v
docker-compose up -d

Docker disk space issues

Clean Docker Resources

# Remove unused containers
docker container prune -f
# Remove unused images
docker image prune -a -f
# Remove unused volumes
docker volume prune -f
# Clean everything (careful!)
docker system prune -a --volumes -f

Email Delivery Issues

SMTP Configuration Problems

Error: "SMTP authentication failed"

Test SMTP Connection

# For production (AWS SES)
# Check SES configuration in EKS
kubectl get configmap pushy-config -n pushy -o yaml | grep SMTP
# Test SES connectivity
kubectl exec -it deployment/pushy-api -n pushy -- nc -zv email-smtp.sa-east-1.amazonaws.com 587
# For local development
docker-compose ps mailhog
open http://localhost:8025

Production Email Setup (AWS SES)

Configure SES

# Current SES configuration in EKS
# Region: sa-east-1
SMTP_HOST=email-smtp.sa-east-1.amazonaws.com
SMTP_PORT=587
SMTP_SECURE=true
FROM_EMAIL=noreply@pushy.ar
# Check SES verified domains
aws ses list-verified-email-addresses --region sa-east-1

Performance Issues

Slow API Response Times

API responses taking more than 1 second

Performance Debugging

# For EKS deployment
# Check pod resources
kubectl top pods -n pushy
# Check HPA status
kubectl get hpa -n pushy
# View pod logs with debug level
kubectl logs -n pushy -l app=pushy-api --tail=100
# Check ElastiCache Redis metrics in AWS Console
# Region: sa-east-1
# For local development
docker stats pushy-api-1

Optimization Tips

✓Increase database connection pool size
✓Add database indexes on frequently queried columns
✓Scale worker instances horizontally
✓Enable Redis query caching

High Memory Usage

Memory Profiling

# Monitor memory usage
docker stats
# Check for memory leaks in Rust
RUST_LOG=debug cargo run --features jemalloc
# Limit container memory
# In docker-compose.yml:
services:
  api:
    mem_limit: 1g
    memswap_limit: 1g

Useful Debug Commands

Quick Debug Commands

Health Checks

# EKS API health check
curl http://a9a18d9bb21ed4e6e9b07bbd4b8d9f16-251019334.sa-east-1.elb.amazonaws.com/health
# Check pod health
kubectl describe pods -n pushy
# Check service endpoints
kubectl get endpoints -n pushy
# SQS queue status (AWS)
aws sqs get-queue-attributes \
  --queue-url https://sqs.sa-east-1.amazonaws.com/YOUR_ACCOUNT_ID/pushy-notifications.fifo \
  --attribute-names All \
  --region sa-east-1
# Local development health
curl http://localhost:3001/health

View Logs

# EKS deployment logs
# API logs
kubectl logs -n pushy -l app=pushy-api -f
# Worker logs
kubectl logs -n pushy -l app=pushy-worker -f
# All pods in namespace
kubectl logs -n pushy --all-containers=true -f
# Local development logs
docker-compose logs -f

Database Queries

# Recent notifications
psql -d pushy -c "SELECT * FROM notifications ORDER BY created_at DESC LIMIT 10;"
# Failed notifications
psql -d pushy -c "SELECT * FROM notifications WHERE status = 'failed' ORDER BY created_at DESC;"
# User count
psql -d pushy -c "SELECT COUNT(*) FROM users;"

Frequently Asked Questions

Q: How do I check the current deployment status?

A: Use these commands to check the EKS deployment:

bash

# Check all Pushy resources
kubectl get all -n pushy
# Check pod logs for errors
kubectl logs -n pushy -l app=pushy-api --tail=50
kubectl logs -n pushy -l app=pushy-worker --tail=50
# Describe pods for events
kubectl describe pods -n pushy
# Check HPA status
kubectl get hpa -n pushy

Q: Why are my notifications not being delivered?

A: Check these common causes:

• Worker pods not running: kubectl get pods -n pushy -l app=pushy-worker
• SQS queue permissions: Check IAM role for EKS service account
• Redis connection issues: Check ElastiCache security groups
• Template not found: Verify Contentful space ID and access token in secrets

Q: How do I scale the system for production?

A: See our Kubernetes deployment guide for production scaling strategies including horizontal pod autoscaling, database connection pooling, and Redis cluster configuration.

Still Need Help?

If you're still experiencing issues, we're here to help:

Contact Support Report an Issue