Common Issues

Port already in use

Error: Bind for 0.0.0.0:4321 failed: port is already allocated

# Find process using port
lsof -i :4321

# Kill process
kill -9 <PID>

# Or stop conflicting container
docker ps | grep 4321
docker stop <container-name>

Network not found

Error: network caddy declared as external, but could not be found

# Create external network
docker network create caddy

# Verify creation
docker network ls | grep caddy

Build fails with dependency errors

Error: npm ERR! code ERESOLVE or version conflicts

# Clean rebuild
docker compose down -v
docker compose build --no-cache
docker compose up -d

Container exits immediately

Container shows "Exited (1)" status

# Check logs for error
docker compose logs web

# Common causes:
# - Syntax error in code
# - Missing environment variable
# - Build step failed

Changes not reflecting

File saved but browser doesn't update

1. 1. Check ENABLE_HMR=true in .env
2. 2. Verify volume mounts in docker-compose.dev.yml
3. 3. Hard refresh browser (Ctrl+Shift+R / Cmd+Shift+R)
4. 4. Restart containers: ./atelier.sh stop && ./atelier.sh dev

Polling not working in Docker

File watching broken on Windows or in some Docker setups

# Enable polling in .env
WATCH_POLL=true

# Restart containers
./atelier.sh dev

WebSocket connection errors

Console shows WebSocket failed to connect

Check browser console for specific error. Often caused by proxy configuration or firewall blocking WebSocket connections.

Out of memory

Error: JavaScript heap out of memory

# Increase Node memory limit in .env
NODE_OPTIONS="--max-old-space-size=4096"

# Rebuild
docker compose build --no-cache

Type errors

TypeScript compilation errors

# Check specific error
npm run build

# Fix type issues
# - Add missing type imports
# - Fix type mismatches
# - Add type assertions if needed

# Skip type checking (not recommended)
# Add to astro.config.mjs:
# vite: {
#   build: {
#     skipTypeCheck: true
#   }
# }

Module not found

Error: Cannot find module '@/components/...'

# Check path alias in tsconfig.json
{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"]
    }
  }
}

# Verify file exists
ls src/components/ComponentName.astro

Certificate not issued

Domain accessible via HTTP but HTTPS times out

1. 1. Verify DNS A record points to server IP
2. 2. Wait for DNS propagation (up to 48 hours)
3. 3. Check Caddy logs: docker logs caddy-proxy
4. 4. Verify ports 80/443 open in firewall

Certificate expired

Browser shows "Your connection is not private"

# Force renewal
docker exec caddy-proxy rm -rf /data/caddy/certificates
docker restart caddy-proxy

# Check renewal happened
docker logs caddy-proxy | grep certificate

Mixed content warnings

HTTPS page loading HTTP resources

Find and update all http:// URLs to https:// or use protocol-relative URLs (//example.com)

Slow page loads

Pages taking >3 seconds to load

1. 1. Check image sizes (optimize with Astro Image component)
2. 2. Review JavaScript bundle size (npm run build)
3. 3. Enable compression (Caddy label: caddy.encode: gzip)
4. 4. Use client:visible for React islands

High memory usage

Container using excessive RAM

# Set memory limits in docker-compose.yml
services:
  web:
    deploy:
      resources:
        limits:
          memory: 2G

Slow builds

npm run build takes >5 minutes

# Increase build concurrency
BUILD_CONCURRENCY=8

# Use faster machine or build server
# Consider CI/CD pipeline for production builds

Merge conflicts

Conflicts when merging branches

# View conflicted files
git status

# Edit files to resolve conflicts
# Remove conflict markers: <<<<<<<, =======, >>>>>>>

# Mark as resolved
git add <file>
git commit

Accidental commit to wrong branch

Committed to main instead of feature branch

# Move commit to new branch
git branch feature/my-feature
git reset HEAD~1 --hard
git checkout feature/my-feature

Need to undo last commit

Committed too early or made mistake

# Undo commit, keep changes
git reset HEAD~1

# Undo commit and changes (dangerous!)
git reset HEAD~1 --hard