Troubleshooting ¶

ddev poweroff
mkdir ~/tmp/testddev
cd ~/tmp/testddev
ddev config --auto
printf "<?php\nphpinfo();\n" > index.php
ddev start
If that starts up fine, there may be an issue specifically with the project you’re trying to start.
Using DDEV with Other Development Environments
DDEV uses your system’s port 80 and 443 by default when projects are running. If you’re using another local development environment (like Lando or Docksal or a native setup), you can either stop the other environment or configure DDEV to use different ports. See troubleshooting for more detailed problem-solving. It’s easiest to stop the other environment when you want to use DDEV, and stop DDEV when you want to use the other environment.
Debug Environment Variables¶
Two environment variables meant for DDEV development may also be useful for broader troubleshooting: DDEV_DEBUG and DDEV_VERBOSE. When enabled, they’ll output more information when DDEV is executing a command. DDEV_VERBOSE can be particularly helpful debugging Dockerfile problems because it outputs complete information about the Dockerfile build stage within the ddev start command.
You can set either one in your current session by running export DDEV_DEBUG=true and export DDEV_VERBOSE=true.
Front-End Development Tools¶
Vite Issues¶
If you’re experiencing issues with Vite development servers (like “Bad Gateway” errors, CORS problems, or HMR not working), see the comprehensive Vite Integration troubleshooting section which covers:
Configuration of web_extra_exposed_ports
CORS and origin settings
Port conflicts and HMR issues
Asset loading problems
Web Server Ports Already Occupied¶
On ddev start you may see a message like this:
Port 443 is not available, using 33001 instead, see https://ddev.com/s/port-conflict
This means that DDEV has detected that it can’t use the expected port (443) in this example, usually because another application is using it. (It can also mean the port was occupied when the ddev-router container was created, and DDEV keeps using the substitute port until the router is recreated, for example by ddev poweroff && ddev start.) If this is OK, you don’t need to take any action. Most users want to use the default ports though (80 and 443) so you may want to figure out what the conflict is and solve it (usually by stopping the competing application).
ddev utility port-diagnose, run from your project directory, can likely explain what’s going on. It checks each port your project needs, identifies the blocking process by name and PID, and suggests how to stop it:
$ ddev utility port-diagnose
Port diagnostics for project: my-project
Port 80 (router HTTP): IN USE by apache2 (PID 1234, cmd=/usr/sbin/apache2 -k start) [Linux]
  sudo systemctl stop apache2 && sudo systemctl disable apache2
Port 443 (router HTTPS): Available
On WSL2, it checks both Linux/WSL2 and Windows. If a port conflict is held by a root-owned process (such as docker-proxy under rootful Docker CE), the tool will ask for permission before running any sudo command, showing the exact command it intends to run. You can pre-approve this with --allow-sudo:
ddev utility port-diagnose --allow-sudo
The --allow-sudo flag is useful in scripts or when you know elevated detection will be needed and want to avoid the interactive prompt. When running non-interactively (CI, pipes) without --allow-sudo, sudo escalation is skipped.
If port-diagnose doesn’t resolve it, the methods below explain how to stop the competing application or configure DDEV to use different ports.
If you do get messages like:
ERROR: for ddev-router Cannot start service ddev-router: Ports are not available: listen tcp 127.0.0.1:XX: bind: An attempt was made to access a socket in a way forbidden by its access permissions.
Error response from daemon: Ports are not available: exposing port TCP 127.0.0.1:8025 -> 0.0.0.0:0: listen tcp 127.0.0.1:8025: bind: Only one usage of each socket address (protocol/network address/port) is normally permitted.
it means some other process is using a needed port. Stop all Docker containers that might be using the port by running ddev poweroff && docker rm -f $(docker ps -aq), then restart Docker.
Method 1: Stop the competing application¶
Consider lando poweroff for Lando, or fin system stop for Docksal, or stop MAMP using GUI interface or stop.sh.
Probably the most common conflicting application is Apache running locally. It can often be stopped gracefully (but temporarily) with:
sudo apachectl stop
sudo systemctl stop apache2 && sudo systemctl disable apache2
Common tools that use port 80 and port 443:
Most people will want to use ports 80 and 443, the default HTTP and HTTPS ports for their projects, and these work fine whenever some other process is not using them. All of the DDEV projects on a given computer can use ports 80 and 443 at the same time. However, if you are not getting the default ports, here are some of the other common processes that could be using ports 80/443 and methods to stop them.
macOS content filtering: Under “Screen Time” → “Choose Screen Time content and privacy settings”, turn off “Content and Privacy” and then reboot. This has been a common issue with macOS Sonoma.
macOS or Linux Homebrew: Look for active processes by running brew services and temporarily running brew services stop individually to see if it has any impact on the conflict.
MAMP (macOS): Stop MAMP.
Apache: Temporarily stop with sudo apachectl stop, permanent stop depends on your environment. On Debian/Ubuntu: sudo systemctl disable apache2 && sudo systemctl stop apache2
nginx (macOS Homebrew): sudo brew services stop nginx or sudo launchctl stop homebrew.mxcl.nginx.
nginx (Ubuntu): sudo systemctl stop nginx or sudo service nginx stop.
VPNKit (macOS): You likely have a Docker container bound to port 80. Do you have containers up for Lando or another Docker-based development environment? If so, stop the other environment.
Lando: If you’ve previously used Lando, try running lando poweroff.
IIS on Windows (can affect WSL2). You’ll have to disable it in the Windows settings.
You can also probe a port with curl to get a hint about which application is responding: curl -I localhost or curl -I -k https://localhost:443.
Method 2: Fix port conflicts by configuring your project to use different ports¶
To configure DDEV to use non-conflicting ports, remove router port configuration from the project and set it globally to different values. This will work for most people:
ddev config global --router-http-port=8080 --router-https-port=8443
ddev config --router-http-port="" --router-https-port=""
ddev restart
This changes all projects’ HTTP URLs to http://yoursite.ddev.site:8080 and the HTTPS URLs to https://yoursite.ddev.site:8443.
We welcome your suggestions based on other issues you’ve run into and your troubleshooting technique.
Security Software Interfering with Port Detection¶
If you see messages like:
Unable to check port availability
Assuming ports are available, see https://ddev.com/s/port-conflict
DDEV will rely on Docker to report actual port conflicts. This can happen when security software intercepts localhost traffic.
Debugging Port Issues on WSL2¶
On WSL2 the port may be occupied either on the traditional Windows side or within the WSL2 distro. ddev utility port-diagnose checks both sides automatically. The ports are shared between Windows and WSL2, so a conflict on either side blocks DDEV.
Database Container Fails to Start¶
Use ddev logs -s db to see what’s wrong.
The most common cause of the database container not coming up is changing the database type or version in the project configuration, so the database server daemon is unable to start using an existing configuration for a different type or version.
To solve this:
Change the configuration in .ddev/config.yaml back to the original configuration.
Export the database with ddev export-db.
Delete the project with ddev delete, or remove just the database volume with ddev utility delete-volume database, which stops the project first if it’s running.
Update .ddev/config.yaml to use the new database type or version.
Start the project and import the database from your export.
“web service unhealthy” or “web service starting” or Exited¶
Use ddev logs to see what’s wrong.




    

The most common cause of the web container being unhealthy is a user-defined .ddev/nginx-full/nginx-site.conf or .ddev/apache/apache-site.conf. Please rename these to <xxx_site.conf> during testing. To figure out what’s wrong with it after you’ve identified that as the problem, use ddev logs and review the error.
Changes to .ddev/nginx-site.conf and .ddev/apache/apache-site.conf take effect only when you do a ddev restart or the equivalent.
No Input File Specified (404) or Forbidden (403)¶
If you get a 404 with “No input file specified” (nginx) or a 403 with “Forbidden” (Apache) when you visit your project, it usually means that no index.php or index.html is being found in the docroot. This can result from:
Misconfigured docroot: If the docroot isn’t where the web server thinks it is, then the web server won’t find index.php. Look at your .ddev/config.yaml to verify it has a docroot containing index.php. It should be a relative path.
Missing index.php: There may not be an index.php or index.html in your project.
ddev start Fails and Logs Contain “failed (28: No space left on device)” - Docker File Space¶
If ddev start fails, it’s most often because the web or db container fails to start. In this case, the error message from ddev start says something like “Failed to start : db container failed: log=, err=container exited, please use ‘ddev logs -s db’ to find out why it failed”. You canddev logs -s db to find out what happened.
If you see any variant of “no space left on device” in the logs when using Docker Desktop, it means you have to increase or clean up Docker’s file space. Increase the “Disk image size” setting under “Resources” in Docker’s Preferences:
If you see “no space left on device” on Linux, it most likely means your filesystem is full.
ddev start Fails with “container failed to become ready”¶
A container fails to become ready when its health check is failing. This can happen to any of the containers, and you can usually find the issue with a docker inspect command.
You may need to install jq for these examples (brew install jq), or remove the | jq from the command and read the raw JSON output.
For the web container:
docker inspect --format "{{json .State.Health }}" ddev-<projectname>-web | jq
For ddev-router:
docker inspect --format "{{json .State.Health }}" ddev-router
For ddev-ssh-agent:
docker inspect --format "{{json .State.Health }}" ddev-ssh-agent
Don’t forget to check logs using ddev logs for the web container, and ddev logs -s db for the db container!
For ddev-router and ddev-ssh-agent: docker logs ddev-router and docker logs ddev-ssh-agent.
ddev start Fails with “Failed to start [project name]: No such container: ddev-router”¶
Deleting the images and re-pulling them generally solves this problem.
Try running the following commands from the host machine:
ddev poweroff
docker rm -f $(docker ps -aq)
docker rmi -f $(docker images -q)
You should then be able to start your DDEV machine.
ddev --version shows an old version¶
If you have installed or upgraded DDEV to the latest version, but when you check the actual version with ddev --version, it shows an older version, please refer to Why do I have an old DDEV?
Trouble Building Dockerfiles¶
The additional .ddev/web-build/Dockerfile capability in DDEV is wonderful, but it can be hard to figure out what to put in there.
The best approach for any significant Dockerfile is to ddev ssh and sudo -s and then one at a time, do the things that you plan to do with a RUN command in the Dockerfile.
For example, if your Dockerfile were
RUN npm install --global forever
You could test it with ddev ssh, sudo -s, and then npm install --global forever.
The error messages you get will be more informative than messages that come when the Dockerfile is processed.
You can also see the output from the full Docker build using either:
ddev utility rebuild
or (see global configuration directory for docker-compose location):
$HOME/.ddev/bin/docker-compose -f .ddev/.ddev-docker-compose-full.yaml --progress=plain build --no-cache
Docker build fails apt-get update, perhaps “SSL certificate problem: self-signed certificate”¶
The Docker build environment (where all projects have a little bit happening) is very sensitive to problems with apt-get update or with TLS certificate authentication. If you ware seeing problems with apt-get update failing, some of these strategies may help:
WSL2: On WSL2 it’s a known issue that the WSL2 environment time can get out of sync with the real time. This is an ongoing problem with WSL2, and can be fixed with various workarounds. One good workaround is to install ntpdate and sudo ntpdate pool.ntp.org to sync the time. The time in WSL2 can get out of sync due to laptop sleeping or other causes. A reboot also fixes it.
VPN: If you are on a packet-inspection VPN, it often causes problems with validation of certificates on internet sites. In that situation you’ll need to get the CA updates required and install them with a custom Dockerfile, as described on Stack Overflow.
Other Docker Build: The Dockerfile build environment is different from the host-side build and different from what you get with ddev ssh. If you’re having trouble with it it may be caused by name resolution or IP connectivity problems, most often caused by a firewall or VPN. Turn off your firewall temporarily and VPN. A good debugging technique would be to do a simple .ddev/web-build/Dockerfile that does RUN curl -I https://www.google.com and then use ddev utility rebuild to see the result. If it gets a 200 result, then your name resolution and internet connectivity are working in the Docker build environment.
DDEV Starts but Browser Can’t Access URL¶
You may see one of these messages in your browser:
403 Forbidden
[url] server IP address could not be found
We can’t connect to the server at [url]
If you get the 403 Forbidden it’s almost always because your docroot is set wrong. You should have something like docroot: web or docroot: "" or docroot: docroot with the relative path to the directory where your index.php lives in the project.
Name resolution: Most people use *.ddev.site URLs, which work great most of the time but require internet access.
*.ddev.site is a wildcard DNS entry that always returns the IP address 127.0.0.1 (localhost). If you’re not connected to the internet, however, or if various other name resolution issues fail, this name resolution won’t work.
While DDEV can create a web server and a Docker network infrastructure for a project, it doesn’t have control of your computer’s name resolution, so its backup technique to make a hostname resolvable by the browser is to add an entry to the hosts file (/etc/hosts on Linux and macOS, C:\Windows\system32\drivers\etc\hosts on traditional Windows).
If you’re not connected to the internet, your browser will not be able to look up *.ddev.site hostnames. DDEV works fine offline, but for your browser to look up names they’ll have to be resolved in a different way.
DDEV assumes that hostnames can be resolved within 3 seconds. That assumption is not valid on all networks or computers, so you can increase the amount of time it waits for resolution. Increasing to 5 seconds, for example: ddev config global --internet-detection-timeout-ms=5000.
If DDEV detects that it can’t look up one of the hostnames assigned to your project for that or other reasons, it will try to add that to the hosts file on your computer, which requires administrative privileges (sudo or Windows UAC).

This technique may not work on Windows WSL2, see below.
DNS Rebinding Prohibited (Mostly on Fritzbox Routers)¶
You may see one of several messages:
Cannot resolve
unknown host
No address associated with hostname
Some DNS servers prevent the use of DNS records that resolve to localhost (127.0.0.1) because in uncontrolled environments this may be used as a form of attack called DNS Rebinding. Since *.ddev.site resolves to 127.0.0.1, they may refuse to resolve, and your browser may be unable to look up a hostname, and give you messages like “ server IP address could not be found” or “We can’t connect to the server at ”.
You verify this is your problem by running ping -c 1 dkkd.ddev.site. If you get “No address associated with hostname” or something of that type, your computer is unable to look up *.ddev.site.
In this case, you can take any one of the following approaches:
Reconfigure your router to allow DNS Rebinding. Many Fritz!Box routers have added default DNS Rebinding disallowal, and they can be reconfigured to allow it. Easy instructions are at Fritz!Box Routers and DDEV. If you have the local dnsmasq DNS server it may also be configured to disallow DNS rebinding, but it’s a simple change to a configuration directive to allow it.
Most computers can use more relaxed DNS resolution if they are not on corporate intranets that have non-internet DNS. So for example, the computer can be set to use 8.8.8.8 (Google) or 1.1.1.1 (Cloudflare) for DNS name resolution, see this article.
If you have control of the router, you can usually change its DHCP settings to choose a public, relaxed DNS server as in #2.
You can live with DDEV trying to edit the /etc/hosts file, which it only has to do when a new name is added to a project.
An extensive discussion of this class of problem is on ddev.com.
Browser Shows Certificate Error for DDEV Sites¶
If your browser shows a certificate warning such as NET::ERR_CERT_AUTHORITY_INVALID, SEC_ERROR_UNKNOWN_ISSUER, or “Your connection is not private” when visiting a DDEV HTTPS URL, the mkcert certificate authority (CA) is not trusted by your browser or OS.
Run ddev utility tls-diagnose to identify the specific problem:
ddev utility tls-diagnose
The command checks mkcert installation, OS trust store, certificate files, and live HTTPS connectivity, and prints actionable fix instructions for each issue it finds.
Common causes and fixes:
mkcert CA not installed in OS trust store — Run mkcert -install and restart your browser.
Firefox on Windows — Firefox on Windows does not use the Windows certificate store. You must import the mkcert CA manually: Firefox Settings → Privacy & Security → View Certificates → Authorities → Import. Select rootCA.pem from the path shown by mkcert -CAROOT. Firefox Nightly, Developer Edition, and ESR each maintain a separate trust store and need the same treatment. On macOS and Linux, standard Firefox works via the OS trust store after mkcert -install; only special builds (Flatpak, snap, Nightly, Developer Edition) may need a manual import.
Linux: certutil not installed — Firefox on Linux relies on certutil (from libnss3-tools) for mkcert -install to register the CA. Install it with sudo apt install libnss3-tools (or brew install nss), then run mkcert -install again.
Expired or CA-rotated certificates — Run ddev poweroff && ddev start to regenerate certificates, or the nuclear option: ddev poweroff && mkcert -uninstall && rm -rf "$(mkcert -CAROOT)" && mkcert -install && ddev start.
On WSL2: The mkcert CA is installed on Windows using mkcert -install in PowerShell. WSL2 then points its $CAROOT at the Windows mkcert directory so both sides use the same CA. ddev utility tls-diagnose checks all the WSL2-specific requirements:
$CAROOT must point to the Windows mkcert directory (e.g. /mnt/c/Users/<user>/AppData/Local/mkcert)
CAROOT must be listed in $WSLENV so it propagates into WSL2 sessions
The mkcert CA must be installed in the Windows certificate store (via mkcert -install in PowerShell)
If any of these are missing, follow the setup instructions in WSL2 and Certificates.
Windows WSL2 Network Issues¶
If you’re using a browser on Windows, accessing a project in WSL2, you can end up with confusing results when your project is listening on a port inside WSL2 while a Windows process is listening on that same port. The way to sort this out is to stop your project inside WSL2, verify that nothing is listening on the port there, and then study the port on the Windows side by visiting it with a browser or using other tools as described above.
Limitations on Symbolic Links (symlinks)¶
Symbolic links are widely used but have specific limitations in many environments beyond DDEV. Here are some of the ways those may affect you:
Crossing mount boundaries: Symlinks may not generally cross between network mounts. In other words, if you have a relative symlink in the root of your project directory on the host that points to ../somefile.txt, that symlink will not be valid inside the container where ../ is a completely different filesystem (and is typically not mounted).
Symlinks to absolute paths: If you have an absolute symlink to something like /Users/xxx/somefile.txt on the host, it will not be resolvable inside the container because /Users is not mounted there. Some tools, especially on Magento 2, may create symlinks to rooted paths, with targets like /var/www/html/path/to/something. These basically can’t make it to the host and may create errors.
Windows restrictions on symlinks: Inside the Docker container on Windows, you may not be able to create a symlink that goes outside the container.
Mutagen restrictions on Windows symlinks: On macOS and Linux (including WSL2) the default .ddev/mutagen/mutagen.yml chooses the posix-raw type of symlink handling. (See Mutagen docs). This basically means that any symlink created will try to sync, regardless of whether it’s valid in the other environment. However, Mutagen does not support posix-raw on traditional Windows, so DDEV uses the portable symlink mode. So on Windows with Mutagen, symlinks have to be strictly limited to relative links that are inside the Mutagen section of the project.
Delete and Re-Download Docker Images¶
In a few unusual cases, the actual downloaded Docker images can somehow get corrupted. Deleting the images will force them to be re-downloaded or rebuilt. This does no harm, as everything is rebuilt, but running ddev start will take longer while it downloads needed resources:
ddev poweroff
docker rm -f $(docker ps -aq) # Stop any other random containers that may be running
docker rmi -f $(docker images -q) # You might have to repeat this to get rid of all images
“Your Docker install has only … available disk space”¶
Weird and bad things happen when Docker or your host system run out of disk space. Here are some ways to solve the problem if you get the warning “Your Docker install has only … available disk space”:
Everybody: Often a ddev delete images and docker builder prune (or docker buildx prune) will free up plenty of space. Consider deleting all images with docker rmi -f $(docker images -q); this does no damage, but the images will have to be re-downloaded.
macOS and traditional Windows: ddev mutagen reset in each project will free up space.
Docker Desktop for Mac allocates a specific amount of docker-related space, and you can increase it. Settings -> Resources -> Disk usage limit.
Colima, Lima, Rancher Desktop: Before changing anything, save away your databases with ddev snapshot -a. Then follow instructions in each of those projects to increase allocated disk space. If you have your databases saved, you can delete your current instance and recreate with new disk constraints, see Docker Installation.
OrbStack and Linux including WSL2 with Docker CE: You are probably out of disk space on the disk where Docker stores images and volumes.