Common Issues & Troubleshooting

Solutions to the most common ProjectSpecter issues.

HTTP/HTTPS Issues

Service Returns 404

Symptoms: Accessing service returns 404 Not Found Causes:

Route not registered in Traefik
Service not on traefik-proxy network
Hostname mismatch in routing rule
Service not running

Diagnosis:

# 1. Check service is running
docker ps | grep myapp

# 2. Check Traefik has the route
curl http://localhost:8080/api/http/routers | jq '.[] | select(.name | contains("myapp"))'

# 3. Check service is on correct network
docker inspect myapp | grep traefik-proxy

# 4. Check hostname matches
# Verify domain used matches the rule in labels

Solutions:

# Add missing route labels to docker-compose.yml:
labels:
  - "traefik.enable=true"
  - "traefik.http.routers.myapp.rule=Host(`myapp.starfleet-command.dev`)"
  - "traefik.http.routers.myapp.entrypoints=websecure"
  - "traefik.http.routers.myapp.tls.certresolver=cloudflare"
  - "traefik.http.services.myapp.loadbalancer.server.port=8080"

# Ensure service is on network:
networks:
  - traefik-proxy

# Redeploy service:
docker compose up -d myapp

502 Bad Gateway

Symptoms: Service returns “502 Bad Gateway” Causes:

Backend service is down
Wrong backend port configured
Service not accessible from Traefik
Network connectivity issue

Diagnosis:

# 1. Check backend service status
docker ps | grep myapp
# Check if it's running and healthy

# 2. Check service logs
docker logs myapp

# 3. Verify configured port
docker inspect myapp | grep -A 5 "ExposedPorts"

# 4. Test direct connection from Traefik
docker exec traefik curl http://myapp:8080

Solutions:

# 1. Fix port mismatch
labels:
  - "traefik.http.services.myapp.loadbalancer.server.port=8080"
  # Change 8080 to actual service port

# 2. Restart backend service
docker compose restart myapp

# 3. Ensure service is on traefik-proxy network
docker network connect traefik-proxy myapp

# 4. Check service health
docker logs myapp | tail -20

Redirect Loop

Symptoms: Continuously redirected between pages Causes:

Middleware misconfiguration
Authentication check failing
Redirect rule pointing to itself
Session cookie not working

Diagnosis:

# Check middleware logs
docker logs descope-auth | grep -i error

# Check Traefik middleware configuration
curl http://localhost:8080/api/http/middlewares

# Test session cookie
curl -I https://myapp.starfleet-command.dev -b "session=test"

Solutions:

# Fix middleware misconfiguration:
# If using descope-verify:
- "traefik.http.routers.myapp.middlewares=descope-verify@docker"

# Make sure middleware exists and is correct:
- "traefik.http.middlewares.descope-verify.forwardauth.address=http://descope-auth:3000/verify"

# Restart services
docker compose restart traefik descope-auth

SSL/TLS Certificate Issues

Certificate Not Generating

Symptoms: HTTPS returns untrusted certificate error Causes:

DNS not resolving
Cloudflare API token invalid
ACME challenge failing
Traefik not configured for HTTPS

Diagnosis:

# 1. Check DNS resolution
nslookup myapp.starfleet-command.dev
# Should return VPS IP

# 2. Check Traefik logs for ACME errors
docker logs traefik | grep -i acme | tail -20

# 3. Verify Cloudflare token
echo $CF_DNS_API_TOKEN
# Should not be empty

# 4. Check route is configured for HTTPS
curl http://localhost:8080/api/http/routers | jq '.[] | select(.name | contains("myapp"))'
# Should show: "entryPoints": ["websecure"]

Solutions:

# 1. Fix DNS
# Go to Cloudflare dashboard
# Add A record: myapp → VPS_IP

# 2. Fix Cloudflare token
# Update .env with valid token
CF_DNS_API_TOKEN=your-valid-token

# Restart Traefik
docker compose down
docker compose up -d traefik

# 3. Ensure route uses websecure entrypoint
labels:
  - "traefik.http.routers.myapp.entrypoints=websecure"
  - "traefik.http.routers.myapp.tls.certresolver=cloudflare"

# 4. Wait for certificate generation
# First certificate takes ~2-5 minutes
# Check logs: docker logs traefik | grep -i certificate

# Clear ACME cache if stuck
docker exec traefik rm /acme/acme.json
docker compose restart traefik

Certificate Expired

Symptoms: Browser shows certificate expired error Causes:

Let’s Encrypt renewal failed
Traefik not running long enough to auto-renew
ACME storage corrupted

Solutions:

# Force certificate renewal
docker exec traefik rm /acme/acme.json
docker compose restart traefik

# Wait 5-10 minutes for new certificate
docker logs traefik | grep -i certificate

# Verify certificate
openssl s_client -connect myapp.starfleet-command.dev:443

Authentication Issues

Can’t Log In

Symptoms: Login page shows error or won’t redirect after login Causes:

Descope service not running
SESSION_SECRET not configured
PROJECT_ID incorrect
Redirect URI not configured in Descope console

Diagnosis:

# 1. Check Descope service
docker ps | grep descope-auth

# 2. Check environment variables
docker inspect descope-auth | grep -E "SESSION_SECRET|DESCOPE_PROJECT_ID"

# 3. Check Descope logs
docker logs descope-auth | tail -20

# 4. Test verify endpoint
curl http://localhost:3000/verify -H "X-Forwarded-URI: /"

Solutions:

# 1. Ensure Descope is running
docker compose up -d descope-auth

# 2. Set SESSION_SECRET
# Generate: openssl rand -base64 32
# Add to .env and docker-compose.yml
SESSION_SECRET=your-generated-secret

# 3. Verify PROJECT_ID
# Check in Descope console
docker exec descope-auth env | grep DESCOPE_PROJECT_ID

# 4. Configure redirect URI in Descope console
# Set to: https://auth.starfleet-command.dev/auth/callback

# Restart Descope
docker compose restart descope-auth

Symptoms: Even after logging in, redirected back to login page Causes:

Session not being created
Cookie domain incorrect
Middleware checking wrong header

Diagnosis:

# Check browser cookies
# Open DevTools → Application → Cookies
# Look for DS-Session cookie
# Should have domain: .starfleet-command.dev

# Check service logs
docker logs descope-auth | grep -i session

# Test session endpoint
curl -H "X-Forwarded-URI: /" -H "X-Forwarded-Proto: https" http://localhost:3000/verify

Solutions:

# 1. Fix cookie domain in server.js
# Line ~77: domain: '.starfleet-command.dev'

# 2. Ensure route uses correct middleware
labels:
  - "traefik.http.routers.myapp.middlewares=descope-verify@docker"

# 3. Clear browser cookies and try again
# DevTools → Application → Cookies → Delete all

# Restart and retry
docker compose restart descope-auth

Docker Issues

Container Won’t Start

Symptoms: Container exits immediately with error Causes:

Configuration error
Port already in use
Insufficient resources
Image not found

Diagnosis:

# Check exit code
docker ps -a | grep myapp

# View full logs
docker logs myapp

# Check if port is in use
netstat -tln | grep :8080

# Verify image exists
docker images | grep myapp

Solutions:

# 1. Fix configuration errors
# Check docker-compose.yml syntax:
docker-compose config

# 2. Free up port
# Find process using port
lsof -i :8080
# Kill process or change port

# 3. Allocate more resources
# Increase Docker memory limit

# 4. Pull correct image
docker pull myapp:latest

# Restart
docker compose up -d

Out of Disk Space

Symptoms: Docker commands fail with “no space left” Causes:

Too many container/image versions
Large logs
Unused volumes

Diagnosis:

# Check disk usage
df -h

# Check Docker disk usage
docker system df

# View largest images
docker images --sort size

# View largest volumes
docker volume ls

Solutions:

# 1. Clean up unused images
docker image prune -a

# 2. Clean up unused volumes
docker volume prune

# 3. Clean up unused containers
docker container prune

# 4. View and limit log size
# Add to docker-compose.yml:
logging:
  driver: "json-file"
  options:
    max-size: "10m"
    max-file: "3"

# 5. Manual cleanup (careful!)
docker system prune -a --volumes

Network Issues

Services Can’t Communicate

Symptoms: Service can’t reach another service Causes:

Services not on same network
Hostname resolution failing
Firewall blocking traffic

Diagnosis:

# Check both services on traefik-proxy network
docker network inspect traefik-proxy | grep -A 20 "Containers"

# Test DNS from one service
docker exec myapp nslookup descope-auth

# Test connectivity
docker exec myapp curl http://descope-auth:3000/health

Solutions:

# 1. Add service to network
docker network connect traefik-proxy myapp

# 2. Use correct service names (container names)
# Wrong: http://192.168.1.1:3000
# Right: http://descope-auth:3000

# 3. Check internal DNS
# Restart DNS: docker network disconnect / connect

# Verify connectivity
docker exec myapp ping descope-auth

Performance Issues

High Memory Usage

Symptoms: Traefik or services consuming excessive memory Causes:

Memory leak in service
Too many connections
Logging too much data

Diagnosis:

# Check memory usage
docker stats

# Check Traefik memory
docker stats traefik

# Profile memory
docker exec traefik memstat

Solutions:

# 1. Set memory limits in docker-compose.yml
services:
  myapp:
    deploy:
      resources:
        limits:
          memory: 512M
        reservations:
          memory: 256M

# 2. Reduce logging verbosity
# In traefik.yml:
log:
  level: WARN  # Instead of DEBUG

# 3. Restart service
docker compose restart myapp

Slow Responses

Symptoms: Services responding slowly Causes:

High latency to backend
Backend service overloaded
Network congestion

Solutions:

# 1. Check backend health
docker logs myapp

# 2. Monitor resource usage
docker stats

# 3. Scale service
# Add more replicas:
services:
  myapp:
    deploy:
      replicas: 3

# 4. Check network
docker exec traefik ping backend-service

# 5. Enable caching in middleware
# Add caching headers in application

Getting Help

Collect Diagnostic Information

# System info
uname -a
docker version

# Service status
docker ps -a

# Traefik logs (last 100 lines)
docker logs traefik | tail -100

# Descope logs
docker logs descope-auth | tail -100

# Docker network info
docker network inspect traefik-proxy

# Disk and memory
df -h
free -h

Check Official Documentation

Traefik: https://doc.traefik.io/
Descope: https://docs.descope.com/
Docker: https://docs.docker.com/
Cloudflare: https://developers.cloudflare.com/

Common Error Messages

Error	Cause	Solution
`address already in use`	Port conflict	Change port or stop other service
`no such file or directory`	Missing volume	Mount volume correctly
`permission denied`	File permissions	`chmod` file or run as correct user
`connection refused`	Service down	Check service is running
`tls: failed to verify certificate`	Bad certificate	Wait for Let’s Encrypt or restart

Next: Contact Support

Home

Getting Started

Components

Troubleshooting

Common Issues & Troubleshooting

Common Issues & Troubleshooting

HTTP/HTTPS Issues

Service Returns 404

502 Bad Gateway

Redirect Loop

SSL/TLS Certificate Issues

Certificate Not Generating

Certificate Expired

Authentication Issues

Can’t Log In

Docker Issues

Container Won’t Start

Out of Disk Space

Network Issues

Services Can’t Communicate

Performance Issues

High Memory Usage

Slow Responses

Getting Help

Collect Diagnostic Information

Check Official Documentation

Common Error Messages

Home

Getting Started

Components

Troubleshooting

​Common Issues & Troubleshooting

​HTTP/HTTPS Issues

​Service Returns 404

​502 Bad Gateway

​Redirect Loop

​SSL/TLS Certificate Issues

​Certificate Not Generating

​Certificate Expired

​Authentication Issues

​Can’t Log In

​Always Redirected to Login

​Docker Issues

​Container Won’t Start

​Out of Disk Space

​Network Issues

​Services Can’t Communicate

​Performance Issues

​High Memory Usage

​Slow Responses

​Getting Help

​Collect Diagnostic Information

​Check Official Documentation

​Common Error Messages

Common Issues & Troubleshooting

HTTP/HTTPS Issues

Service Returns 404

502 Bad Gateway

Redirect Loop

SSL/TLS Certificate Issues

Certificate Not Generating

Certificate Expired

Authentication Issues

Can’t Log In

Always Redirected to Login

Docker Issues

Container Won’t Start

Out of Disk Space

Network Issues

Services Can’t Communicate

Performance Issues

High Memory Usage

Slow Responses

Getting Help

Collect Diagnostic Information

Check Official Documentation

Common Error Messages