Local by flywheel fix

Local by Flywheel — Recovery Playbook

The error you're probably seeing

Uh-oh! Unable to start site.
Error: Command failed:
C:\Users\<USER>\AppData\Roaming\Local\lightning-services\mysql-8...\mysqladmin.exe --host=::1 ping
mysqladmin: connect to server at '::1' failed
error: 'Lost connection to MySQL server at 'reading initial communication packet', system error: 0'

This almost always means port conflict in sites.json. Local sometimes assigns the same port to two services (e.g., MySQL and nginx both on 10012), and only one of them can actually bind to it.

Fast fix: edit sites.json

Where it lives

OS	Path
Windows	%APPDATA%\Local\sites.json (= C:\Users\<you>\AppData\Roaming\Local\sites.json)
macOS	~/Library/Application Support/Local/sites.json
Linux	~/.config/Local/sites.json

Diagnose

# Find your site by name
python -c "
import json
with open(r'C:/Users/<you>/AppData/Roaming/Local/sites.json','r',encoding='utf-8') as f:
    data = json.load(f)
for site_id, site in data.items():
    if 'YOUR-SITE-NAME' in str(site).lower():
        print('id:', site_id)
        for svc, cfg in site['services'].items():
            print(f\"  {svc}: ports={cfg.get('ports')}\")
"

If two services share a port, that's the bug.

Fix

import json
path = r'C:/Users/<you>/AppData/Roaming/Local/sites.json'
with open(path, 'r', encoding='utf-8') as f:
    data = json.load(f)

site_id = 'YOUR_SITE_ID'   # from the diagnose step
# Pick an unused port in the 10000-10100 range
data[site_id]['services']['mysql']['ports']['MYSQL'] = [10010]

with open(path, 'w', encoding='utf-8') as f:
    json.dump(data, f, indent=2, ensure_ascii=False)
print('saved')

Then fully quit Local (right-click tray icon → Quit), reopen, start the site.

Pick a free port

# Windows
netstat -ano -p tcp | findstr "LISTENING"

# macOS / Linux
lsof -iTCP -sTCP:LISTEN -nP

Anything in the 10000–10100 range that isn't listed is fair game for Local services.

Other common Local breakages

1. app/sql/ directory missing

Symptom: site exists in Local UI but the data dir is gone — usually after a Windows backup tool or antivirus deleted it.

Fix:

# Stop the site
# Restore from Local's "Time Capsule" backup (Local → site → Snapshots)
# OR if no backup, delete the site and re-import from a `.wpress` export

2. Stale mysqld.lock file

Symptom: MySQL won't start, error log says "Another instance is running".

Fix:

# Path varies by version
rm "C:/Users/<you>/Local Sites/<sitename>/app/sql/mysqld.lock"

3. Lightning-services not installed

Symptom: error references missing lightning-services\<service>-<version>\<binary>.exe.

Fix:

# Folder layout
ls "C:/Users/<you>/AppData/Roaming/Local/lightning-services/"
# Should contain: mailpit-*, mariadb-*, mysql-*, nginx-*, php-*

# Reinstall: Local → Preferences → Advanced → "Reinstall Lightning Services"

4. .local domain not resolving

Symptom: test-wordpress-site.local → DNS_PROBE_FINISHED_NXDOMAIN.

Fix on Windows:

# Ensure Local's hosts entries are written
# Local → Preferences → Advanced → "Update hosts file" (requires admin)

# Verify
type C:\Windows\System32\drivers\etc\hosts | findstr local

Fix on macOS:

sudo dscacheutil -flushcache
sudo killall -HUP mDNSResponder

5. WordPress white screen / fatal error after switch to Local

Usually because wp-config.php was set up for a different environment. Local injects DB credentials automatically — don't override DB_HOST, DB_USER, DB_PASSWORD, DB_NAME in your wp-config.php.

6. Site Shell missing wp-cli

Local's "Site Shell" auto-loads wp-cli. If it doesn't:

# Inside Local's Site Shell
wp --info        # should show the path

# If missing, reinstall Local (sometimes fixes broken PATH)

Useful paths

What	Path
Site configs	%APPDATA%\Local\sites.json
Lightning services	%APPDATA%\Local\lightning-services\
Site files	~\Local Sites\<sitename>\app\public\
Site SQL data	~\Local Sites\<sitename>\app\sql\
Site logs (nginx, php)	~\Local Sites\<sitename>\logs\
Local app preferences	%APPDATA%\Local\preferences.json

When all else fails

1. Export the site to a .wpress file from inside the broken Local (Tools → Local Connect or All-in-One Migration plugin if site is reachable)
2. Quit Local completely
3. Delete the site from Local UI (does NOT delete files, but back them up first to be safe)
4. Create a new site with a different name
5. Import the .wpress file

This burns 10 minutes but resolves any issue rooted in stale Local config.

Prevention

• Don't put your Local Sites folder inside OneDrive/Dropbox/Google Drive. They mangle SQLite locks and corrupt MySQL data files. Use a plain local folder like C:\Users\<you>\Local Sites\.
• Keep antivirus exceptions for the Local Sites folder.
• Don't run Local at the same time as a system MySQL/MariaDB (e.g., Laravel Herd's bundled MySQL). Pick one.

Real-world story

A developer working on a WordPress site on Local Windows kept hitting:

error: 'Lost connection to MySQL server at 'reading initial communication packet'

Tried: reinstalling Local, restarting Windows, disabling antivirus, deleting and recreating the site. None worked.

Real cause: sites.json had nginx.HTTP: [10012] AND mysql.MYSQL: [10012]. Both services trying to bind the same port. Nginx grabbed it first; MySQL silently failed.

Fix: change mysql.MYSQL to [10010] in sites.json, restart Local. Site started in seconds.

---

Skill maintained at https://github.com/OmarEltak/wp-rescue-kit