How-To Guide

Debugging Guide

Methodical techniques for diagnosing issues and finding root causes.

The debugging mindset

Effective debugging requires systematic observation, not guessing. Follow this approach:

1. Reproduce the issue

Can you make it happen again? Document the exact steps. If it's intermittent, note the conditions.

• What did you do immediately before the error?
• Does it happen every time or randomly?
• Does it happen in both dev and prod?

2. Isolate the problem

Remove variables. Test one component at a time. Narrow down where the issue lives.

3. Check the obvious first

Environment variables set? Containers running? Network accessible? Dependencies installed?

4. Read error messages carefully

Error messages tell you what failed. Stack traces tell you where. Read the entire message.

Container debugging

Docker containers isolate the application. Use these tools to inspect what's happening inside.

Check container status

 # List all containers
docker compose ps

# Check if containers are running
docker compose ps --all

# View container resource usage
docker stats 

View container logs

 # All services
docker compose logs

# Specific service
docker compose logs web

# Follow logs in real-time
docker compose logs -f web

# Last 100 lines
docker compose logs --tail=100 web

# Since timestamp
docker compose logs --since 2024-01-16T10:00:00 web 

Execute commands inside container

 # Open shell in running container
docker compose exec web sh

# Run single command
docker compose exec web npm run build

# Check environment variables
docker compose exec web env

# View file system
docker compose exec web ls -la /app 

Inspect container configuration

 # View full container config
docker inspect <container-name>

# Get specific value (IP address)
docker inspect -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' <container-name>

# Check environment variables
docker inspect -f '{{range .Config.Env}}{{println .}}{{end}}' <container-name> 

Log analysis techniques

Logs contain the truth. Learn to parse them effectively.

Grep for patterns

 # Find errors
docker compose logs | grep -i error

# Find specific module
docker compose logs | grep "astro"

# Count occurrences
docker compose logs | grep -c "failed"

# Show context around match (3 lines before/after)
docker compose logs | grep -C 3 "error" 

Filter by timestamp

 # Logs from last 5 minutes
docker compose logs --since 5m

# Logs between timestamps
docker compose logs --since 2024-01-16T10:00:00 --until 2024-01-16T11:00:00

# Follow new logs only
docker compose logs -f --tail=0 

Save logs for analysis

 # Save to file
docker compose logs > debug-$(date +%Y%m%d-%H%M%S).log

# Save errors only
docker compose logs 2>&1 | grep -i error > errors.log

# Compress large logs
docker compose logs | gzip > logs.gz 

Common log patterns to look for

• error, fatal, exception - Critical failures
• warn, warning - Potential issues
• ECONNREFUSED - Service not reachable
• EADDRINUSE - Port conflict
• 404, 500, 502 - HTTP errors
• timeout - Performance/network issues
• permission denied - File system permissions

Network inspection

Container networking can be complex. Verify connectivity and routing.

Check port bindings

 # View exposed ports
docker compose port web 4321

# Check if port is listening
lsof -i :4321

# Test local connection
curl -I http://localhost:4321 

Inspect Docker networks

 # List networks
docker network ls

# Inspect specific network
docker network inspect caddy

# See which containers are on a network
docker network inspect caddy --format '{{range .Containers}}{{.Name}} {{end}}' 

Test container-to-container connectivity

 # Ping from one container to another (if ping installed)
docker compose exec web ping -c 3 db

# DNS resolution test
docker compose exec web nslookup db

# HTTP request test
docker compose exec web curl http://api:3000/health 

Browser DevTools Network tab

Open DevTools (F12) → Network tab. Reload the page and look for:

• Failed requests (red) - check status code and response
• Slow requests (waterfall) - identify performance bottlenecks
• WebSocket connections - verify HMR is connecting
• CORS errors - check server headers
• 404s - missing assets or incorrect paths

Caddy reverse proxy debugging

 # Check Caddy logs
docker logs caddy-proxy

# Test upstream connection
docker compose exec caddy curl http://web:4321

# Verify labels applied correctly
docker inspect <container> | grep caddy 

Performance profiling

Slow builds? Page load issues? Profile to find the bottleneck.

Measure build time

 # Time the build process
time npm run build

# Verbose Astro build (shows what's slow)
npm run build -- --verbose

# Check bundle size
npm run build && du -sh dist/ 

Browser Performance tab

DevTools → Performance → Record page load

• Look for long tasks (yellow/red bars)
• Check network waterfall for blocking resources
• Identify slow JavaScript execution
• Measure Largest Contentful Paint (LCP)

Container resource usage

 # Real-time resource stats
docker stats

# Memory usage of specific container
docker stats web --no-stream

# Check disk usage
docker system df 

Lighthouse audit

 # Install globally
npm install -g lighthouse

# Run audit
lighthouse https://your-domain.com --view

# Or use DevTools → Lighthouse tab 

Browser debugging

Most frontend issues reveal themselves in browser DevTools.

Console tab

• Errors (red) - JavaScript exceptions, failed network requests
• Warnings (yellow) - Potential issues, deprecated APIs
• Logs (gray) - Debug output from console.log()
• Filter by level, source file, or search term

Elements tab

Inspect DOM structure, computed styles, event listeners

• Right-click element → Inspect
• Edit HTML/CSS live to test fixes
• Check computed styles for specificity issues
• Force element state (:hover, :focus)

Sources tab (debugger)

 // Add breakpoints in JavaScript code
function problematicFunction() {
  debugger;  // Execution pauses here
  const result = complexCalculation();
  console.log(result);
} 

Step through code line by line. Inspect variable values. Watch call stack.

Application tab

• View localStorage, sessionStorage, cookies
• Inspect service workers (PWA)
• Check cache storage
• Clear storage to test fresh state

Git debugging

When did this break? Find the commit that introduced the bug.

Find when something changed

 # View file history
git log -p src/components/Header.astro

# See who changed a line
git blame src/components/Header.astro

# Search commit messages
git log --grep="header" --oneline 

Binary search for bad commit (git bisect)

 # Start bisect session
git bisect start

# Mark current state as bad
git bisect bad

# Mark last known good commit
git bisect good abc123

# Test current state, then mark as good or bad
npm run build
git bisect good  # or: git bisect bad

# Repeat until bisect finds the culprit
# When done:
git bisect reset 

Compare working tree to remote

 # Fetch latest from remote
git fetch origin

# Compare local to remote
git diff main origin/main

# See unpushed commits
git log origin/main..main 

When to ask for help

You don't have to solve everything alone. Here's when and how to ask.

Before asking

✓ Searched error message on Google/Stack Overflow
✓ Checked this documentation and common issues
✓ Tried to reproduce in a clean environment
✓ Read the full error message (including stack trace)
✓ Verified environment variables and configuration

What to include when asking

• What you're trying to do - The goal, not just the error
• What you expected - The desired outcome
• What actually happened - Error messages, screenshots
• Steps to reproduce - Exactly how to make it happen
• Environment details - OS, Docker version, Node version
• What you've tried - Show your debugging effort
• Relevant logs - Not all logs, just the relevant part

Where to ask

• GitHub Issues - For bugs or feature requests in the codebase
• Astro Discord - For Astro-specific questions
• Stack Overflow - For general programming questions
• Docker Community - For containerization issues

Rubber duck debugging

Explain the problem out loud (or in writing) to an inanimate object. Often you'll find the answer yourself while explaining. It works.

Debugging checklist

When stuck, work through this systematic checklist.

Can you reproduce the issue reliably?
Did you read the complete error message?
Are all containers running? (docker compose ps)
Are environment variables set correctly?
What do the logs say? (docker compose logs)
Any errors in browser console? (F12)
Can you isolate the problem to one component/file?
Does it work in a clean environment?
Did you try restarting containers?
Did you clear browser cache/storage?
Have you searched for the error message online?
Did recent git commits introduce the issue?

Still stuck? Take a break. Fresh eyes often spot what you missed. Then review this checklist again.