Troubleshooting

Troubleshooting

This guide covers common issues you might encounter with DAMP and provides step-by-step solutions to get you back to productive development quickly.

Quick Diagnostic Checklist

Before diving into specific issues, run through this quick checklist:

1. Check DAMP Status

   Open DAMP dashboard and verify all services show green status:

   • 🟢 Docker Engine

2. Verify Project Status

   In the project grid, ensure your project shows:

   • 🟢 Running status (not stopped or error)

3. Test Basic Connectivity

   Try accessing your project:

   • HTTP: http://my-project.local
   • HTTPS: https://my-project.local
   • Direct IP: http://localhost:port (check port in DAMP)

4. Check System Resources

   Ensure adequate system resources:

   • RAM: At least 4GB available
   • Disk space: Sufficient for containers and data
   • CPU: Not at 100% constantly

Installation Issues

DAMP Won’t Install

Windows Installation Problems

Symptoms: Installer fails or DAMP won’t start after installation

Common Causes & Solutions:

Windows Defender Blocking

Solution:

1. Click “More info” on Windows Defender warning
2. Click “Run anyway”
3. Add DAMP folder to exclusions: Windows Security → Virus & threat protection → Exclusions

Missing .NET Framework

Solution:

1. Download Microsoft .NET Framework 4.8 or later
2. Install and restart computer
3. Retry DAMP installation

Insufficient Permissions

Solution:

1. Right-click installer
2. Select “Run as administrator”
3. Complete installation with admin privileges

Project Creation Issues

Project Creation Fails

Image Download Problems

Symptoms: Project creation gets stuck on “Downloading images”

Solutions:

1. Check internet connection: Ensure stable internet for image downloads
2. Clear Docker cache:

   docker system prune -a

3. Restart Docker: Restart Docker Desktop
4. Try again: Delete failed project and recreate

Insufficient Disk Space

Symptoms: “No space left on device” during project creation

Solutions:

1. Free up disk space: Delete unnecessary files
2. Clean Docker:

   docker system df              # Check Docker disk usage
   docker system prune -a        # Remove unused images/containers
   docker volume prune           # Remove unused volumes

3. Move Docker data: Change Docker Desktop data location to drive with more space

Runtime Issues

Project Won’t Start

Database Connection Issues

Symptoms: Application can’t connect to database

Solutions:

1. Verify database is running:

   docker ps | grep mysql

2. Check database credentials: Verify .env file has correct settings
3. Test connection manually:

   mysql -h 127.0.0.1 -P 3306 -u username -p

4. Reset database: Right-click project → “Reset Database”

Website Access Issues

Domain Not Resolving

Symptoms: my-project.local doesn’t load

Diagnostic Steps:

1. Test DNS resolution:

   nslookup my-project.local
   ping my-project.local

2. Check Hosts file: Verify that my-project.local is mapped to 127.0.0.1
   • Windows: C:\Windows\System32\drivers\etc\hosts
3. Try different browsers: Some browsers cache DNS aggressively
4. Clear DNS cache:

   # Windows
   ipconfig /flushdns
   
   # macOS
   sudo dscacheutil -flushcache
   
   # Linux
   sudo systemctl restart systemd-resolved

Getting Help

Community Support

• Discord Community: Join the DAMP Discord server
• Stack Overflow: Tag questions with damp-development

Professional Support

• Priority Support: Available for teams and enterprises
• Custom Training: On-site training for development teams
• Consulting Services: Help with complex setups and integrations

Reporting Bugs

When reporting issues:

1. Gather diagnostic information:

   damp diagnostics --export # Not yet implemented

2. Include system information:

   • Operating system and version
   • Docker Desktop version
   • DAMP version
   • Error messages and logs

3. Provide reproduction steps: Clear steps to reproduce the issue

4. Submit GitHub issue: Use the issue template for complete information

Troubleshooting Pro Tips

• Check logs first - Most issues are quickly diagnosed from log files
• Try a different browser - Browser-specific issues are common
• Restart services systematically - Docker, then DAMP, then project
• Keep DAMP updated - Many issues are fixed in newer versions
• Document workarounds - Share solutions with your team

Most DAMP issues are quickly resolved with the solutions in this guide. When in doubt, start with the diagnostic checklist and work systematically through the potential causes.