Troubleshooting guide

Resolve common issues you might encounter when self-hosting Screenshothis. This guide provides step-by-step solutions, diagnostic commands, and prevention strategies to keep your instance running smoothly.

Get the latest help: Check the Screenshothis repository and GitHub Issues for the most recent troubleshooting information and community solutions.

Quick diagnostics

Start here to quickly assess your system’s health and identify issues:

Check application health

Test if your Screenshothis instance is responding:

# Basic health check
curl -f http://localhost:3000/health

# Detailed health status
curl -s http://localhost:3000/health | jq '.'

You should see a 200 response with health status information

Verify readiness

Check if the application is ready to serve requests:

# Check if application is ready
curl -f http://localhost:3000/health/ready

# Check if application is alive
curl -f http://localhost:3000/health/live

Review recent logs

Examine logs for error messages and clues:

# View recent application logs
docker logs screenshothis --tail 50

# Follow logs in real-time
docker logs -f screenshothis

# View logs with timestamps
docker logs -t screenshothis --since 1h

Common startup issues

Application won’t start

When your Screenshothis instance fails to start or exits immediately:

Missing environment variables

Symptoms: Container exits immediately with environment variable errorsDiagnose the issue:

# Check which variables are missing
docker logs screenshothis 2>&1 | grep -i "missing\|required\|undefined"

# Verify your environment file
cat .env.production | grep -v '^#' | grep -v '^$'

# List all environment variables in container
docker exec screenshothis env | sort

Fix the problem:

Ensure all required variables are set in your .env file
Key required variables include:
- DATABASE_URL
- BETTER_AUTH_SECRET
- S3 configuration (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, etc.)
- VITE_SERVER_URL (for frontend)

# Example fix - add missing variables
echo "BETTER_AUTH_SECRET=$(openssl rand -base64 32)" >> .env.production
echo "DEFAULT_API_KEY_PREFIX=ss_live" >> .env.production

Never use default development secrets in production. Generate unique, secure values for all secrets.

Port already in use

Symptoms: Error: listen EADDRINUSE: address already in use :::3000Diagnose and fix:

# Check what's using port 3000
sudo netstat -tulpn | grep :3000
# Or use lsof
sudo lsof -i :3000

# Kill the process using the port (if safe to do so)
sudo kill -9 $(sudo lsof -t -i:3000)

# Alternative: Change the port in your environment
echo "PORT=3001" >> .env.production

Prevention: Use a reverse proxy like nginx to handle port 80/443 and proxy to your application.

Docker build failures

Symptoms: Docker build fails with dependency or build errorsDiagnose and fix:

# Clear Docker cache and rebuild
docker system prune -f
docker build --no-cache -t screenshothis:latest .

# Build with verbose output for debugging
docker build -t screenshothis:latest . 2>&1 | tee build.log

# Check available disk space
df -h

# Clear unused Docker resources
docker system df
docker system prune -a

Common fixes:

Ensure sufficient disk space (at least 2GB free)
Check internet connectivity for package downloads
Verify Node.js version compatibility

Database connection problems

PostgreSQL connectivity issues

When you can’t connect to your PostgreSQL database:

Connection refused errors

Symptoms: Connection refused, Database does not exist, or timeout errorsDiagnose the issue:

# Test database connectivity directly
psql "$DATABASE_URL" -c "SELECT version();"

# Check if PostgreSQL container is running
docker ps | grep postgres
docker logs postgres-container

# Test connection with individual components
psql -h localhost -p 5432 -U screenshothis -d screenshothis

Fix the problem:

Verify PostgreSQL is running

# Start PostgreSQL if stopped
docker-compose up -d postgres

# Check container health
docker ps --filter "name=postgres"

Verify database exists

# List available databases
psql -h localhost -U screenshothis -l

# Create database if missing
createdb -h localhost -U screenshothis screenshothis

Test connection

# Use the exact DATABASE_URL from your environment
psql "$DATABASE_URL" -c "SELECT 1;"

You should see a successful connection and query result

Emergency reset (⚠️ This deletes all data):

# Only use if you need to start fresh
dropdb -h localhost -U screenshothis screenshothis
createdb -h localhost -U screenshothis screenshothis
pnpm run db:push

Migration and schema errors

Symptoms: Migration failed, schema errors, or table not found errorsFix schema issues:

# Check current schema status
pnpm run db:studio

# Apply schema changes (development)
pnpm run db:push

# For production, use migrations
pnpm run db:generate
pnpm run db:migrate

# Reset schema (⚠️ destructive)
pnpm run db:reset

Check migration status:

# View migration history
psql "$DATABASE_URL" -c "SELECT * FROM drizzle.__drizzle_migrations;"

# Check table structure
psql "$DATABASE_URL" -c "\dt"

Redis connectivity issues

Cache and session problems

When Redis connections fail or caching doesn’t work:

Redis connection failed

Symptoms: Redis connection to localhost:6379 failed or session issuesDiagnose and fix:

# Check if Redis is running
docker ps | grep redis
docker logs redis-container

# Test Redis connection directly
redis-cli ping
redis-cli -u "$REDIS_URL" ping

# Start Redis if not running
docker-compose up -d redis

# Test with authentication if required
redis-cli -a your-password ping

Verify Redis configuration:

# Check Redis server info
redis-cli info server

# Test basic operations
redis-cli set test "hello"
redis-cli get test
redis-cli del test

Authentication errors

Symptoms: NOAUTH Authentication required or permission deniedFix authentication:

# Check if Redis requires authentication
docker exec redis-container redis-cli config get requirepass

# Update REDIS_URL with credentials
export REDIS_URL="redis://username:password@localhost:6379"

# Test authenticated connection
redis-cli -u "$REDIS_URL" ping

Redis URL formats:

# No authentication
REDIS_URL=redis://localhost:6379

# With password
REDIS_URL=redis://:password@localhost:6379

# With username and password
REDIS_URL=redis://username:password@localhost:6379

Storage and S3 issues

Screenshot upload failures

When screenshots can’t be saved to storage:

S3 access denied errors

Symptoms: AccessDenied, Forbidden, or upload failure errorsDiagnose the issue:

# Test S3 credentials and access
aws s3 ls s3://your-bucket --region your-region

# Check current AWS configuration
aws configure list

# Verify bucket exists and is accessible
aws s3api head-bucket --bucket your-bucket

Fix permissions:

Verify credentials

Check that your AWS credentials are correct and active:

# Test basic AWS connectivity
aws sts get-caller-identity

# List accessible buckets
aws s3 ls

Check bucket permissions

Ensure your IAM user has the required S3 permissions:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "s3:GetObject",
        "s3:PutObject",
        "s3:DeleteObject"
      ],
      "Resource": "arn:aws:s3:::your-bucket/*"
    },
    {
      "Effect": "Allow",
      "Action": "s3:ListBucket",
      "Resource": "arn:aws:s3:::your-bucket"
    }
  ]
}

Test upload

# Test file upload
echo "test" > test.txt
aws s3 cp test.txt s3://your-bucket/test.txt
aws s3 rm s3://your-bucket/test.txt
rm test.txt

Upload and deletion should complete without errors

MinIO local development issues

Symptoms: MinIO connection fails or bucket access denied during local developmentFix MinIO issues:

Check MinIO status

# Verify MinIO container is running
docker ps | grep minio
docker logs minio-container

# Test MinIO health
curl -f http://localhost:9000/minio/health/live

Access MinIO console

Open http://localhost:9001 in your browser
Login with:
- Username: screenshothis-access-key
- Password: screenshothis-secret-key
Create the bucket screenshothis-bucket if it doesn’t exist

Reset MinIO if needed

# Stop and remove MinIO data
docker-compose down
docker volume rm $(docker volume ls -q | grep minio)

# Start fresh
docker-compose up -d minio

# Wait for startup, then create bucket via console

Verify configuration:

# Check environment variables match MinIO setup
echo $AWS_ACCESS_KEY_ID      # Should be: screenshothis-access-key
echo $AWS_SECRET_ACCESS_KEY  # Should be: screenshothis-secret-key
echo $AWS_URL                # Should be: http://localhost:9000

Screenshot generation problems

Capture failures and timeouts

When screenshots fail to generate or take too long:

Screenshot timeouts

Symptoms: Screenshot generation timed out or requests timing outDiagnose performance:

# Monitor system resources
docker stats screenshothis

# Check screenshot processing logs
docker logs -f screenshothis | grep -i screenshot

# Monitor concurrent operations
docker exec screenshothis ps aux | grep chrome

Optimize performance:

# Increase timeout in environment variables
echo "SCREENSHOT_TIMEOUT=60000" >> .env.production

# Reduce concurrent screenshots if system is overloaded
echo "MAX_CONCURRENT_SCREENSHOTS=5" >> .env.production

# Optimize default screenshot settings
echo "MAX_SCREENSHOT_WIDTH=1920" >> .env.production
echo "MAX_SCREENSHOT_HEIGHT=1080" >> .env.production

System requirements: Ensure adequate resources:

CPU: At least 2 cores for production
RAM: Minimum 2GB, recommended 4GB+
Disk: At least 5GB free space

Memory issues and crashes

Symptoms: Out of memory errors, container restarts, or system freezesMonitor memory usage:

# Check container memory usage
docker stats screenshothis --no-stream

# Check system memory
free -h
df -h

Fix memory issues:

Docker Compose
Docker Run
Kubernetes

# In docker-compose.yml
services:
  screenshothis:
    deploy:
      resources:
        limits:
          memory: 2G
        reservations:
          memory: 1G

# Run with memory limits
docker run -m 2g --memory-swap 2g screenshothis:latest

# In deployment.yaml
resources:
  requests:
    memory: "1Gi"
    cpu: "500m"
  limits:
    memory: "2Gi"
    cpu: "1000m"

Memory optimization:

# Reduce concurrent operations
MAX_CONCURRENT_SCREENSHOTS=3

# Enable garbage collection
NODE_OPTIONS="--max-old-space-size=1024 --gc-interval=100"

# Optimize Chrome memory usage
CHROMIUM_ARGS="--memory-pressure-off --max_old_space_size=1024"

Chromium browser issues

Symptoms: Chromium fails to start, crashes, or sandbox errorsCommon Chromium fixes:

Check security settings

For Docker deployments, you may need to adjust security settings:

# Run with additional security options
docker run --security-opt seccomp=unconfined screenshothis

# Or disable sandboxing (less secure)
docker run --cap-add=SYS_ADMIN screenshothis

Verify dependencies

Ensure all required system dependencies are installed:

# In your Dockerfile, install required packages
RUN apt-get update && apt-get install -y \
    chromium \
    chromium-sandbox \
    fonts-liberation \
    libappindicator3-1 \
    libasound2 \
    libatk-bridge2.0-0 \
    libdrm2 \
    libgtk-3-0 \
    libnspr4 \
    libnss3 \
    libx11-xcb1 \
    libxcomposite1 \
    libxdamage1 \
    libxrandr2 \
    xdg-utils \
    && rm -rf /var/lib/apt/lists/*

Configure Chrome arguments

# Add Chrome optimization flags
CHROMIUM_ARGS="--no-sandbox --disable-dev-shm-usage --disable-extensions --disable-gpu"

For Kubernetes deployments:

# Add security context to pod spec
securityContext:
  runAsUser: 1001
  runAsGroup: 1001
  capabilities:
    add:
      - SYS_ADMIN

Performance optimization

System resource management

When your instance is slow or consuming too many resources:

High CPU and memory usage

Monitor resource consumption:

# Real-time resource monitoring
docker stats
htop
iostat 5

# Check for memory leaks
docker exec screenshothis node --expose-gc -e "
  console.log('Memory before GC:', process.memoryUsage());
  global.gc();
  console.log('Memory after GC:', process.memoryUsage());
"

Optimization strategies:

Limit Concurrency
Optimize Screenshots
Memory Management

# Reduce concurrent operations
MAX_CONCURRENT_SCREENSHOTS=5
RATE_LIMIT_MAX_REQUESTS=50
RATE_LIMIT_WINDOW_MS=60000

# Use more efficient settings
DEFAULT_VIEWPORT_WIDTH=1280
DEFAULT_VIEWPORT_HEIGHT=720
MAX_PAGE_LOAD_TIMEOUT=15000
SCREENSHOT_TIMEOUT=30000

# Enable garbage collection and memory limits
NODE_OPTIONS="--max-old-space-size=1024 --gc-interval=100"
CHROMIUM_ARGS="--memory-pressure-off --disable-extensions"

Slow screenshot generation

Diagnose slow performance:

# Time screenshot generation
time curl "http://localhost:3000/v1/screenshots/take?api_key=test&url=https://example.com"

# Monitor Chrome processes
docker exec screenshothis ps aux | grep chrome

# Check system load
uptime
vmstat 5

Speed optimization:

# Optimize browser settings for speed
CHROMIUM_ARGS="--no-sandbox --disable-dev-shm-usage --disable-extensions --disable-images"

# Reduce quality for faster generation
DEFAULT_QUALITY=70
MAX_SCREENSHOT_WIDTH=1920
MAX_SCREENSHOT_HEIGHT=1080

# Optimize page load timeout
MAX_PAGE_LOAD_TIMEOUT=20000

Network and connectivity

External service connectivity

When you can’t reach databases, S3, or other external services:

External service connectivity

Test connectivity from your server:

# Test database connectivity
ping your-database-host
telnet your-database-host 5432

# Test S3 connectivity
ping s3.amazonaws.com
curl -I https://s3.amazonaws.com

# Check DNS resolution
nslookup your-database-host
dig your-database-host

# Test from within container
docker exec screenshothis ping google.com
docker exec screenshothis curl -v https://s3.amazonaws.com

Fix connectivity issues:

Check firewall rules

# Check firewall status
sudo ufw status

# Allow outbound connections
sudo ufw allow out 5432/tcp  # PostgreSQL
sudo ufw allow out 6379/tcp  # Redis
sudo ufw allow out 443/tcp   # HTTPS
sudo ufw allow out 53/tcp    # DNS

Verify DNS resolution

# Check DNS servers
cat /etc/resolv.conf

# Test DNS resolution
nslookup your-service.com
dig @8.8.8.8 your-service.com

Test with curl

# Test HTTP connectivity
curl -v https://your-service.com

# Test with timeout
curl --connect-timeout 10 https://your-service.com

Firewall and security group issues

Check and configure firewall rules:

UFW (Ubuntu)
iptables
AWS Security Groups

# Check current rules
sudo ufw status numbered

# Allow application ports
sudo ufw allow 3000/tcp

# Allow outbound database connections
sudo ufw allow out 5432/tcp
sudo ufw allow out 6379/tcp

# Reset UFW if needed
sudo ufw --force reset
sudo ufw enable

# Check current rules
sudo iptables -L -n

# Allow specific ports
sudo iptables -A INPUT -p tcp --dport 3000 -j ACCEPT
sudo iptables -A OUTPUT -p tcp --dport 5432 -j ACCEPT

# Save rules (Ubuntu/Debian)
sudo iptables-save > /etc/iptables/rules.v4

# Check security group rules
aws ec2 describe-security-groups --group-ids sg-your-group-id

# Add inbound rule for port 3000
aws ec2 authorize-security-group-ingress \
  --group-id sg-your-group-id \
  --protocol tcp \
  --port 3000 \
  --cidr 0.0.0.0/0

Monitoring and diagnostics

System health monitoring

Set up monitoring to prevent issues before they occur:

Enable health monitoring

Create monitoring scripts for system health:

# Health check script
#!/bin/bash
# save as health-check.sh

echo "=== Screenshothis Health Check ==="
echo "Timestamp: $(date)"

# Check application health
echo "Application health:"
curl -f http://localhost:3000/health && echo " ✓ Healthy" || echo " ✗ Unhealthy"

# Check disk space
echo "Disk usage:"
df -h | awk '$5 > 80 {print "WARNING: " $0}'

# Check memory usage
echo "Memory usage:"
free -h

# Check Docker containers
echo "Container status:"
docker ps --format "table {{.Names}}\t{{.Status}}"

Set up automated monitoring

Add monitoring to your crontab:

# Edit crontab
crontab -e

# Add these entries:
# Health check every 5 minutes
*/5 * * * * /path/to/health-check.sh >> /var/log/screenshothis-health.log 2>&1

# Disk space check every 15 minutes
*/15 * * * * df -h | awk '$5 > 85 {print "CRITICAL: Disk space low on " $0}' | mail -s "Disk Space Alert" admin@yourdomain.com

# Log rotation check
0 2 * * * docker logs screenshothis --tail 1000 > /var/log/screenshothis-daily.log

Monitor application metrics

Enable detailed application monitoring:

# Add metrics to environment
echo "ENABLE_METRICS=true" >> .env.production
echo "METRICS_PORT=9090" >> .env.production

# View metrics
curl http://localhost:9090/metrics

# Monitor specific endpoints
watch -n 5 'curl -s http://localhost:3000/health | jq .'

Getting help and support

When you need additional assistance:

GitHub Issues

Search existing issues or create a new one with detailed error information

Community Discussions

Join community discussions for questions and ideas

Documentation

Browse complete self-hosting documentation and guides

Configuration Reference

Check all available configuration options and examples

Collecting diagnostic information

When reporting issues, include this diagnostic information:

System information

# Collect system details
echo "=== System Information ===" > diagnostic.txt
uname -a >> diagnostic.txt
docker version >> diagnostic.txt
docker-compose version >> diagnostic.txt
lsb_release -a >> diagnostic.txt 2>/dev/null

Application logs

# Collect recent application logs
echo "=== Application Logs ===" >> diagnostic.txt
docker logs screenshothis --tail 200 >> diagnostic.txt

Configuration (redacted)

# Collect environment variables (remove sensitive data)
echo "=== Environment Configuration ===" >> diagnostic.txt
env | grep -v PASSWORD | grep -v SECRET | grep -v KEY | sort >> diagnostic.txt

Container status

# Collect container information
echo "=== Container Status ===" >> diagnostic.txt
docker ps -a >> diagnostic.txt
docker stats --no-stream >> diagnostic.txt

Prevention and maintenance

Regular maintenance tasks

Keep your Screenshothis instance healthy with regular maintenance:

Weekly maintenance

Perform these tasks weekly:

# Clean up Docker resources
docker system prune -f

# Check log file sizes
du -sh /var/log/
docker logs screenshothis --tail 1 | wc -l

# Update base images (when needed)
docker pull postgres:15
docker pull redis:7-alpine

# Backup database
pg_dump "$DATABASE_URL" > backup_$(date +%Y%m%d).sql

Monthly maintenance

Perform these tasks monthly:

# Update system packages
sudo apt update && sudo apt upgrade -y

# Check SSL certificate expiry
echo | openssl s_client -connect yourdomain.com:443 2>/dev/null | openssl x509 -noout -dates

# Review resource usage trends
docker stats --no-stream
df -h

# Test backup restoration
# (Test this in a separate environment)

Monitoring alerts

Set up alerts for:

Disk space > 85% full
Memory usage > 90%
Health check failures
SSL certificate expiry (30 days before)
High error rates in logs
Database connection failures

Example alert script:

#!/bin/bash
# save as alert-check.sh

# Check disk space
DISK_USAGE=$(df / | awk 'NR==2 {print $5}' | sed 's/%//')
if [ $DISK_USAGE -gt 85 ]; then
    echo "ALERT: Disk usage is ${DISK_USAGE}%" | mail -s "Disk Space Alert" admin@yourdomain.com
fi

# Check if application is responding
if ! curl -f http://localhost:3000/health >/dev/null 2>&1; then
    echo "ALERT: Screenshothis health check failed" | mail -s "Health Check Alert" admin@yourdomain.com
fi

Next steps

Configuration Guide

Optimize your configuration for better performance and reliability

Deployment Guide

Learn advanced deployment strategies and scaling options

API Reference

Complete API documentation for your self-hosted instance

GitHub Repository

Report issues and contribute to the project

Getting Started

SDKs

Self-Hosting

API Reference

Health & Monitoring

Troubleshooting

Troubleshooting guide

Quick diagnostics

Common startup issues

Application won’t start

Database connection problems

PostgreSQL connectivity issues

Redis connectivity issues

Cache and session problems

Storage and S3 issues

Screenshot upload failures

Screenshot generation problems

Capture failures and timeouts

Performance optimization

System resource management

Network and connectivity

External service connectivity

Monitoring and diagnostics

System health monitoring

Getting help and support

GitHub Issues

Community Discussions

Documentation

Configuration Reference

Collecting diagnostic information

Prevention and maintenance

Regular maintenance tasks

Next steps

Configuration Guide

Deployment Guide

API Reference

GitHub Repository

Getting Started

SDKs

Self-Hosting

API Reference

Health & Monitoring

Documentation Index

​Troubleshooting guide

​Quick diagnostics

​Common startup issues

​Application won’t start

​Database connection problems

​PostgreSQL connectivity issues

​Redis connectivity issues

​Cache and session problems

​Storage and S3 issues

​Screenshot upload failures

​Screenshot generation problems

​Capture failures and timeouts

​Performance optimization

​System resource management

​Network and connectivity

​External service connectivity

​Monitoring and diagnostics

​System health monitoring

​Getting help and support

GitHub Issues

Community Discussions

Documentation

Configuration Reference

​Collecting diagnostic information

​Prevention and maintenance

​Regular maintenance tasks

​Next steps

Configuration Guide

Deployment Guide

API Reference

GitHub Repository

Troubleshooting guide

Quick diagnostics

Common startup issues

Application won’t start

Database connection problems

PostgreSQL connectivity issues

Redis connectivity issues

Cache and session problems

Storage and S3 issues

Screenshot upload failures

Screenshot generation problems

Capture failures and timeouts

Performance optimization

System resource management

Network and connectivity

External service connectivity

Monitoring and diagnostics

System health monitoring

Getting help and support

Collecting diagnostic information

Prevention and maintenance

Regular maintenance tasks

Next steps