---
title: "Troubleshooting | Parity docs"
description: "The findings parity check reports most often, what each means and how to fix it, from container engines and WSL 2 to line endings, ports and arm64."
url: https://parity.apps.wayne.edu/docs/troubleshooting.html
llms: https://parity.apps.wayne.edu/llms.txt
generator: Squire agent-ready
---

# Troubleshooting [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#troubleshooting)

Start with `parity check`. It prints one line per finding and, under each one that needs it, the fix for your OS. Fix the first one, then run it again. This page explains the common findings in more depth.

## No container engine [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#no-container-engine)

> No container engine is installed (Parity looked for docker and podman).

Parity drives an engine; it does not bring one. Install one:

| Computer | Recommended | Also works |
| --- | --- | --- |
| Windows | Podman Desktop (free): `winget install --id RedHat.Podman-Desktop -e` | Docker Desktop, if you already have it |
| macOS | Podman Desktop (free): `brew install --cask podman-desktop` | Docker Desktop, if you already have it |
| Linux | Podman, from your distribution's package | Docker Engine with its Compose plugin |

Open a new terminal afterwards and run `parity check` again.

### Which engine, and licenses [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#which-engine-and-licenses)

Podman Desktop is free, which is why it is the recommendation. Docker Desktop's terms ask larger organizations for a paid subscription; if you already have Docker Desktop, Parity works with it as it is. On Linux, Podman and Docker Engine are both free.

With both installed, Parity uses the one that is running, Docker first when both are, and `parity check` names the other ("Podman is here too"). To choose for good, save it once (the desktop app's Settings does the same):

```text
parity engine podman
```

`parity engine` alone says which one Parity uses and why; `parity engine auto` goes back to the running one. For one terminal only, set `PARITY_ENGINE` to `podman` or `docker`; it wins over the saved choice:

```powershell
$env:PARITY_ENGINE = "podman"
```

```sh
export PARITY_ENGINE=podman
```

## The engine is not running [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#the-engine-is-not-running)

Parity found the engine but could not reach it. Open the engine's app (or start its service) and wait until it says it is ready. With Podman on Windows or macOS, `podman machine start` starts the virtual machine it runs in. On Linux with Docker Engine, `sudo systemctl start docker`.

### Podman's machine runs, Podman in it does not answer [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#podman-s-machine-runs-podman-in-it-does-not-answer)

> Podman's machine is running, but the Podman service inside it is not answering.

Seen on Windows when another WSL distribution with systemd (Ubuntu, say) also has a user 1000: WSL distributions share one cgroup tree, so the machine's own user 1000 session cannot start (`podman machine ssh "systemctl status user@1000.service"` says "Device or resource busy"). Stop the other distribution (`wsl --terminate <name>`), then `podman machine stop` and `podman machine start`. Or make the machine rootful: `podman machine stop`, `podman machine set --rootful`, `podman machine start`.

## Docker Compose v2 is missing [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#docker-compose-v2-is-missing)

Parity needs Compose v2 to start the three containers. Docker Desktop includes it; update Docker Desktop if it is old. On Linux with Docker Engine, install the Compose plugin (`docker-compose-plugin` on Debian and Ubuntu).

With Podman, Parity runs Docker Compose v2 through `podman compose`, which finds it on your PATH. podman-compose (the Python program) is a different tool, and Parity refuses it. On Linux, install Docker Compose from your distribution (`sudo dnf install docker-compose` on Fedora and RHEL, `sudo apt-get install docker-compose-v2` on Ubuntu).

### Podman's API socket is off [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#podman-s-api-socket-is-off)

> Docker Compose is here, but Podman's API socket is off, and Compose talks to Podman through it.

On Linux, Docker Compose reaches Podman through Podman's API socket, which systemd starts when asked: `systemctl --user enable --now podman.socket` (rootless, the usual case) or `sudo systemctl enable --now podman.socket` (rootful). On Windows and macOS the machine forwards it for you.

## Rootless Podman and file ownership [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#rootless-podman-and-file-ownership)

Under rootless Podman the container's root is you. In mount mode Parity runs the app with `userns_mode: keep-id`, mapped to the image's `citadel` user, so inside the container your files belong to `citadel`, as the source owner on Citadel. As the container starts, Parity gives the `writable` paths to Apache's group, group-writable, as Citadel's deploy does, so Apache, the deployments and the cron entries can all write them. Files Apache writes show on your side with a high user id from your subuid range; you can still delete them. Parity never uses Podman's `:U` mount option, which would hand your folder to the container's ids on your own disk.

## Windows [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#windows)

### Windows containers [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#windows-containers)

> The engine runs Windows containers; Citadel's images are Linux images.

Switch the engine to Linux containers. In Docker Desktop: right-click its icon by the clock, "Switch to Linux containers...".

### Not on WSL 2 [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#not-on-wsl-2)

> Docker Desktop is not using WSL 2 (it is on the older Hyper-V engine).

Docker Desktop, Settings, General: turn on "Use the WSL 2 based engine", then Apply and restart. Podman Desktop uses WSL 2 on Windows by default.

If WSL itself is missing, `wsl --install` in an administrator PowerShell installs it, after a restart.

### Podman lost its connection [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#podman-lost-its-connection)

> Health check: could not ask the app: podman lost its connection twice

Podman on Windows reaches its machine over SSH, and a busy WSL can drop that connection for a moment (`ssh: handshake failed` in the details). `parity test` tries each read once more after two seconds, so a single drop no longer fails a healthy app; this message means it dropped twice in a row. Run `parity test` again. If it keeps happening, `parity check` shows the engine, and `podman machine stop` then `podman machine start` resets the connection.

## Line endings [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#line-endings)

> These files Citadel runs have Windows line endings (CRLF), which its shell cannot run: build.sh.

Git on Windows often checks files out with CRLF line endings. Citadel's shell cannot run a script with them, so neither can Parity, and this is exactly the kind of thing Parity is for: it fails here, not on Citadel. The fix tells git to keep Unix line endings for those files, then checks them out again. On Windows:

```powershell
Add-Content .gitattributes "*.sh text eol=lf"
git add --renormalize .
Remove-Item build.sh; git checkout -- build.sh
```

`parity check` prints the exact lines for your files. Commit `.gitattributes` so everyone gets the same endings.

## Pages load from localhost:5173 [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#pages-load-from-localhost-5173)

While `npm run dev` runs, Laravel's Vite plugin writes a `public/hot` file, and every page then loads its scripts and styles from the dev server on `localhost:5173` instead of the built assets. Citadel never runs that dev server and `public/hot` is never deployed, so a page that looks fine through the dev server is not what Citadel serves. `parity check` warns (`vite-hot`) when the public folder has the `hot` file, and `parity test` fails a front page that loads its assets from the dev server. The fix: stop `npm run dev`, delete `public/hot`, and run `npm run build` (Citadel serves the built assets).

## A port is taken [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#a-port-is-taken)

> 8080 taken by another program.

Stop that program, or set `http_port` (or `database.port` for MySQL) in `parity.json` to a free port. Two Parity apps can run side by side on different ports. When the app that holds the port is this one, already running, `parity check` says so and there is nothing to fix.

## Port 8443 is taken [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#port-8443-is-taken)

> Port 8443 is taken by another program.

`parity up` says this when `"https": true` and another program already listens on 8443. Unlike `http_port` and `database.port`, Parity's https port is fixed at 8443, so there is no field to move it. Stop the other program, or set `"https": false` in `parity.json` if this app does not need local https.

## The browser still warns about the certificate [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#the-browser-still-warns-about-the-certificate)

The app answers over https, but the browser still says the connection is not secure: this computer's certificate stores do not trust the app's local CA yet. Work through these:

- **Run `parity trust`** once on this computer. On Windows and macOS it puts the CA in your user store, no admin needed. `parity check`'s `https.trust` finding says OK when your store trusts the CA, and warns with `Fix: parity trust` when it does not (it never fails, so CI stays green).
- **Linux:** the system store needs sudo, which Parity will not ask for, so it prints the commands and you run the one that matches your distro: `sudo cp <ca.crt> /usr/local/share/ca-certificates/parity-<name>.crt && sudo update-ca-certificates` on Debian and Ubuntu, `sudo cp <ca.crt> /etc/pki/ca-trust/source/anchors/parity-<name>.crt && sudo update-ca-trust extract` on Fedora and RHEL. When `certutil` is on your PATH and `~/.pki/nssdb` exists, Parity also adds the CA to Chrome's NSS database itself.
- **Firefox** keeps its own store on every OS: import the app's `ca.crt` (the path Parity prints) under Settings, Certificates, Authorities.

If `server_name` changed since Parity made the CA, the CA will not sign for the new name: delete the CA folder Parity names, run `parity up` again, then `parity trust`.

## Citadel's image is not here [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#citadel-s-image-is-not-here)

> citadel/php-apache:8.5r3 is not on this computer yet.

Run `parity image get` ([Citadel's images](https://parity.apps.wayne.edu/docs/guides/images.html) has the three ways it downloads).

> Citadel has not published a download for citadel/php-apache:8.4r5 yet.

Parity runs Citadel's own images only, and this one has no download yet. Set `image` in `parity.json` to a tag that `parity image list` can download, or ask the Citadel team to publish it ([When Citadel has not published an image yet](https://parity.apps.wayne.edu/docs/guides/images.html#when-citadel-has-not-published-an-image-yet)).

> citadel/php-apache:8.5r3 is here, but it is not the build Citadel runs.

The image has Citadel's tag but a different id, usually from an old download or a local build. `parity image get` replaces it with Citadel's own.

## arm64 computers [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#arm64-computers)

Citadel's images are amd64. On an arm64 computer they run emulated, under Rosetta or QEMU: slower, but real, and still Citadel's own image.

- **Apple Silicon.** Docker Desktop runs amd64 images with Rosetta when "Use Rosetta for x86_64/amd64 emulation on Apple Silicon" is on (Settings, General); with it off, they run on slower QEMU emulation. Podman's machine uses Rosetta when it is turned on (macOS 26 or later), else QEMU. `parity check` says whether your engine uses Rosetta and gives the steps to turn it on; when it cannot read Docker Desktop's setting, it says so in an info line.
- **Windows on Arm.** Citadel's images and MySQL 5.6 run under QEMU emulation, which is slow. Give the first `parity up` a few minutes.
- **arm64 Linux.** Install QEMU's amd64 emulation once: `docker run --privileged --rm tonistiigi/binfmt --install amd64`. Without it, Citadel's image and MySQL 5.6 cannot start.

## The app does not come up [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#the-app-does-not-come-up)

`parity up` shows the last lines that explain a failure, and the whole output is in `.parity/up.log`. Then:

- **The build failed**: your `build.sh` failed the way it would on Citadel. Run `parity up --verbose` to watch it.
- **A deployment failed**: a script in `deployments/` exited non-zero. `parity logs app` shows its output.
- **The health check never passed**: `parity logs app --apache` shows Apache's error log, where a PHP fatal error lands. `parity shell` opens a shell in the container to look around.

Exit 1 means your app's build, deployments or health check failed; exit 2 means Parity could not run it at all.

## The proxy step warns that the front page is slow [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#the-proxy-step-warns-that-the-front-page-is-slow)

> HAProxy is up, but the app's front page took longer than 10 seconds to answer (its health check passed). parity logs app shows why.

The proxy step starts HAProxy only after the app's own health check has passed, then asks it for `/`, waiting 10 seconds per try. A slow first page (cold caches, a slow first query) now warns instead of failing, because the proxy itself is fine. `parity logs app` shows what the page was doing while it took so long.

## MySQL refuses the app's password [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#mysql-refuses-the-app-s-password)

> \[FAIL\] MySQL is running, but it refuses the app's password: its volume (parity-hello_mysql-data) was made with other passwords than .parity/mysql.env.

MySQL's image reads `.parity/mysql.env` only once, when it first makes the database volume. After that the volume keeps the passwords it was made with. So when `.parity/` is deleted (`git clean -x`, a fresh clone of the same app) or a second folder runs an app with the same `name`, Parity writes new passwords and MySQL refuses them. Its health check still passes, because `mysqladmin ping` says yes even when access is denied, so `parity up` signs in as the app before it goes on, and stops here instead of leaving every page to say "Access denied". Three ways out:

- `parity down --volumes`, then `parity up`: a fresh local database (its data is erased).
- Put the old `.parity/mysql.env` back, if you still have it.
- Give this copy its own `name` in `parity.json`, so it gets its own containers and volume (and its own ports).

The same check catches a `database.name` changed after the volume was made ("database ... is not the app's"): MySQL made the database and the app's user once, for the old name. Start over with `parity down --volumes`, or set the name back.

## The running app's own checks [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#the-running-app-s-own-checks)

With a `parity.json` and a running engine, `parity check` also asks the running app four things: whether `APP_KEY` is set (Laravel apps), whether the folders in `writable` are there and writable by Apache, whether the app can sign in to its MySQL, and whether any migrations are pending (Laravel apps with MySQL). With the app stopped it says so and skips them. The failures:

### APP_KEY is not set [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#app-key-is-not-set)

> APP_KEY is not set.

The local `.env` has no `APP_KEY`, or it is still the placeholder from `.env.example`, and Laravel cannot boot without one. Generate one for the local app:

```text
parity run -- php artisan key:generate
```

Parity reads the value only to compare it; it never prints it.

### A writable folder is not writable by Apache [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#a-writable-folder-is-not-writable-by-apache)

> storage is not writable by Apache.

Each folder in `writable` is given to Apache's group, group-writable, as the app container starts. When one is not writable, start the app over so the entrypoint does it again:

```text
parity down
parity up
```

When the folder is not in the app at all, `parity check` warns instead ("is not in the app, so Parity could not check it"): create the folder, or remove it from `writable`.

### The app cannot sign in to its MySQL [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#the-app-cannot-sign-in-to-its-mysql)

> ERROR 2002 (HY000): Can't connect to MySQL server on 'mysql' (111)

`parity check` signs in to the local MySQL the way the app will, so a refused connection or a refused password shows up in the check, not on every page. It usually means the database volume was made before the current `.parity/mysql.env` (a deleted `.parity/`, a second folder with the same app name); [MySQL refuses the app's password](https://parity.apps.wayne.edu/docs/troubleshooting.html#mysql-refuses-the-app-s-password) has the three ways out, the first being:

```text
parity down --volumes
parity up
```

## The front page answers 503 a minute after parity up [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#the-front-page-answers-503-a-minute-after-parity-up)

> \[FAIL\] GET / answered 503, a server error

and `parity logs proxy` says `backend app has no server available` or `DNS timeout status`. That is Parity 0.1.0 on Podman: its proxy asked Docker's DNS address for the app container on every engine, Podman's DNS lives elsewhere, and about a minute after `parity up` HAProxy gave up on the app. Releases after 0.1.0 ask whichever engine runs the proxy. Upgrade Parity, then `parity down` and `parity up` (or, until you can upgrade, `PARITY_ENGINE=docker`).

## parity test says Proxy trust [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#parity-test-says-proxy-trust)

> \[WARN\] Proxy trust 1 request had forwarded headers HELMET did not trust: the app trusts another proxy address than Parity's. Set HELMET_PROXIES (or TRUSTED_PROXIES) in the app's local .env to Parity's proxy network; see docs/troubleshooting.md.

This is a note, not a failure: `parity test` still passes. It means HELMET, the stack's security-headers package, saw `X-Forwarded-Proto` and `X-Forwarded-For` from an address it does not trust, and ignored them. On Citadel the `citadel` preset trusts `172.18.0.1`, Citadel's HAProxy, and stays right; on your machine Parity's proxy reaches the app from its own address, so the app reads every request as plain http from the proxy's address. To fix it, set `HELMET_PROXIES` (or the app's `TRUSTED_PROXIES`) in the local `.env` to the address Parity's proxy uses: `parity logs app` shows the log line, and its remote address is that address.

## Mount mode and the kit's deployments [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#mount-mode-and-the-kit-s-deployments)

**My vendor/ or node_modules/ changed after parity up.** In mount mode the container works in your own folder, so the kit's deployments (which call `scripts/release.sh`) install Composer and npm packages and migrate there. `parity init --from-squire` warns about it. Use bake mode, or set `SQUIRE_NPM=skip` and `SQUIRE_MIGRATE=0` in `.env.squire` where skipping them is safe.

## No parity.json here [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#no-parity-json-here)

`parity up` stops, and `parity check` counts it as a failure, each with one of these two lines naming the command that writes the file:

```text
no parity.json in <dir>, but this app has Squire's kit. Run: parity init --from-squire
no parity.json in <dir>. Run: parity init (it asks nothing; it guesses, and you edit).
```

The first is for a folder that has Squire's kit (docker-compose.squire.yml). The second is for a folder that does not.

## parity.json is refused [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#parity-json-is-refused)

Parity reads `parity.json` before it starts anything, and says which field is wrong:

- **A cron schedule "is not one Citadel takes".** Citadel's dashboard takes `*`, `*/N` or a list for minute and hour, and `*` or a list for the rest. Write a range as a list (`1,2,3,4,5`, not `1-5`), and a day as its number.
- **A cron command with `;`, `&&`, `|`, `>` or `$`.** On Citadel that would run on the host, outside your app. Put the steps in a script in the app and name it.
- **`sign_in "fake"` needs a local environment.** SESAME's fake driver refuses to boot anywhere else, so set `environment` to `local`, `development`, `dev`, `testing` or `test`.
- **An unknown field.** A typo is caught rather than ignored. [parity.json](https://parity.apps.wayne.edu/docs/reference/parity-json.html) lists every field.

## A cron entry does nothing [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#a-cron-entry-does-nothing)

`parity logs cron:<name>` shows its stdout and stderr files, and `parity logs app` shows each run as it starts and ends. Entries start at the top of the minute, so give one a minute. They run as `prisoner` from `/citadel/src`, as on Citadel: a command that works in `parity shell` but not as a cron entry usually needs a file `prisoner` cannot read or write.

## Starting over [#](https://parity.apps.wayne.edu/docs/troubleshooting.html#starting-over)

`parity down --volumes` stops the app and empties the local database and logs (fake data only, but it is gone). `.parity/` is rewritten on every `parity up`, so deleting it is safe too, except for the local MySQL passwords: the next `parity up` makes new ones, and an old database volume will not open with them. Run `parity down --volumes` first. If you forgot, `parity up` says so at its MySQL step ([MySQL refuses the app's password](https://parity.apps.wayne.edu/docs/troubleshooting.html#mysql-refuses-the-app-s-password)).
