Local development troubleshooting

Fix the common problems when you pull and push with DDEV: SSH keys, a blocked address, host key warnings, backups, Git divergence, drop-ins, mixed content, and Windows.

Parts of this feature are still being built. The Not yet section lists them.

Start with ddev avaloi doctor. It checks DDEV, Docker, the tools on your computer, your API key and its scopes, the connection to the server, the host key, your SSH key in DDEV, rsync, and the Git remote. It tells you what to fix.

DDEV prints error=exit status N and exits with 1 when a command fails. The number N is the add-on's exit code: 2 usage, 3 not signed in, 4 refused, 5 a transfer or check failed, 6 not found. The message above it says what happened.

"No Avaloi API key"

The add-on looks for AVALOI_API_KEY in your shell, then for the command in AVALOI_API_KEY_COMMAND, then for a key stored in DDEV, and then asks. Create a key under Account settings, API keys. Keep it out of project files.

"Avaloi did not accept the API key"

The key is wrong, was revoked, or belongs to another account. Create a new one and update the one place you keep it.

"The API key may not do this"

The key lacks a scope. sites:read covers init, status, code, and a pull over SSH. Pulling from live, and pushing the database or uploads, also need backups:write and jobs:read. The person behind the key needs database access on the site. See API keys and scopes.

"No SSH key is loaded in DDEV's ssh agent"

Run ddev auth ssh. It loads the key that is on your Avaloi account.

"The server refused your SSH key"

The public half of the key is not on your Avaloi account, or your role cannot deploy code to the site. Add it under Account settings, SSH keys. See Clone with Git. Then run ddev auth ssh.

Do not retry in a loop. After 5 failed logins the server blocks your address for an hour. The add-on stops at the first refusal for that reason. If you are blocked, wait an hour, or use a different network. ddev avaloi doctor --login tries one login and tells you the result.

The connection

"Host key mismatch"

The server shows a different SSH key than Avaloi reports. Nothing was sent. If the environment was moved or restored, run ddev avaloi init --refresh. If it keeps happening on a network you do not trust, stop and contact support.

The first connection trusts the host

Until Avaloi reports a host key fingerprint, the add-on remembers the key it sees on the first connection and refuses any change later. It says so once. It never turns host key checking off.

"Cannot reach the Avaloi API"

Check your network, a proxy, or a VPN. For a test server, set AVALOI_API_URL. Plain http is accepted for localhost only.

The address or port changed

ddev avaloi status warns when Avaloi reports a new host or port. Run ddev avaloi init --refresh.

Code and Git

"You have uncommitted changes in files Git tracks"

The add-on will not pull over work you have not saved. Commit or stash, then pull again. Nothing was changed.

"Your main and avaloi/main have both moved"

Your commits and the server's both moved. Run ddev avaloi pull --code --rebase, or merge yourself with git merge avaloi/main. The add-on never discards your commits.

"git push failed"

The remote moved ahead. Pull first, then push again. A push to live is refused by design: push to staging and promote.

"You are on a detached HEAD"

ddev avaloi code --release live leaves you on live's commit. Run ddev avaloi code to go back to your branch before you push.

My plugin or theme changed after a pull

A pull changes tracked files only through Git. Look at git log and git status. The add-on does not delete a tracked file.

Database and uploads

"The dump is incomplete"

The connection dropped during the export. Your local database was not changed. Run the pull again. For a large database, pull from a backup with --method backup.

"The download is damaged" or "ended at N bytes"

The backup download was cut. The add-on deleted it. Run the pull again: a download resumes when the server allows it.

"Avaloi refused this pull" on live

Live takes no account SSH keys. Use --method backup, which is the default for live.

The site redirects to the live address, or images do not load

The address rewrite did not run, or the site stores the address in a place it did not reach. Run ddev wp option get siteurl. If it is not your DDEV address, run ddev wp search-replace https://OLD-ADDRESS $(ddev describe -j | jq -r .raw.primary_url) --all-tables-with-prefix --skip-columns=guid.

Mixed content warnings

Open the site over https://NAME.ddev.site. If your browser does not trust the DDEV certificate, run mkcert -install once and restart the browser. On WSL2, install mkcert's root certificate in Windows as well.

A cache drop-in slows or breaks the local site

If your repository tracks advanced-cache.php, object-cache.php, db.php, or sunrise.php, a pull keeps it and warns you. Those files talk to services your computer does not run.

For a file you track, switch it off in wp-config-local.php. The warning prints the line, for example define('WP_CACHE', false); or define('WP_REDIS_DISABLED', true);. The Redis cache drop-in that Avaloi runs on its servers is not in your repository, and it does not come down.
For a file you do not track, pass --disable-dropins to rename it to NAME.avaloi-disabled. Rename it back to turn it on.

The add-on never deletes or rewrites a tracked file.

Mail from the local site

DDEV catches all mail in Mailpit: run ddev launch -m. The add-on switches off mail and backup plugins in the local database that hold live credentials. The list is in .ddev/.avaloi-deactivate. Edit it freely.

Windows, macOS, and ports

Windows 11: use WSL2 with Docker Engine inside it, and keep the project in the Linux home folder. A project under C:\ is slow and can fail. If containers cannot resolve names (apt, the network), put {"dns": ["1.1.1.1", "8.8.8.8"]} in /etc/docker/daemon.json inside WSL and restart Docker.
Docker Desktop on Windows, and macOS: not tested yet. Turn on Mutagen for large sites with ddev config --performance-mode=mutagen.
Port 80 or 443 is taken: DDEV picks another, and your address carries a port, such as https://my-site.ddev.site:33001. The address rewrite handles it.
A pull is slow: use --uploads-days 30 or --max-size 50M, or pull only what you need: --db, --uploads, --code.

Still stuck

Run ddev avaloi status and ddev avaloi doctor, and send the output to Avaloi support. The output holds no secret.

Not yet

Docker Desktop on Windows, macOS, and arm64 Linux are not tested yet.
Avaloi does not report the server's SSH host key yet, so the first connection is trusted and pinned from then on.

Still stuck?

Email [email protected] with your site name and what you tried, or send us a message.