# Local By Flywheel Fix

> When Local by Flywheel won't start a site, MySQL fails with "Lost connection to MySQL server", lightning-services crashes, port conflicts, or "Unable to start site" errors. Triggers on "Local by Flywheel", "Local won't start", "MySQL error in Local", "lightning-services", "mysqladmin connect failed", "Local site stuck", "site won't boot", "Cannot connect to MySQL".

- Skill: `omareltak/local-by-flywheel-fix` (Agent Skill)
- Install (CLI): `npx skillmds@latest add omareltak/local-by-flywheel-fix`
- Raw SKILL.md: https://api.skillmd.com/api/skills/omareltak/local-by-flywheel-fix/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: OmarEltak (https://skillmd.com/u/omareltak)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/omareltak/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

```bash
# 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

```python
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

```bash
# 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:
```bash
# 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:
```bash
# 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:
```bash
# 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:
```bash
# 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:
```bash
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:
```bash
# 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*