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#
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#
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):
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:
$env:PARITY_ENGINE = "podman"
export PARITY_ENGINE=podman
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#
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#
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#
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#
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#
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#
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#
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#
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:
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#
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#
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#
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#
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 trustonce on this computer. On Windows and macOS it puts the CA in your user store, no admin needed.parity check'shttps.trustfinding says OK when your store trusts the CA, and warns withFix: parity trustwhen 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-certificateson Debian and Ubuntu,sudo cp <ca.crt> /etc/pki/ca-trust/source/anchors/parity-<name>.crt && sudo update-ca-trust extracton Fedora and RHEL. Whencertutilis on your PATH and~/.pki/nssdbexists, 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#
citadel/php-apache:8.5r3 is not on this computer yet.
Run parity image get (Citadel's images 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).
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#
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 checksays 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 upa 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#
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.shfailed the way it would on Citadel. Runparity up --verboseto watch it. - A deployment failed: a script in
deployments/exited non-zero.parity logs appshows its output. - The health check never passed:
parity logs app --apacheshows Apache's error log, where a PHP fatal error lands.parity shellopens 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#
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#
[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, thenparity up: a fresh local database (its data is erased).- Put the old
.parity/mysql.envback, if you still have it. - Give this copy its own
nameinparity.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#
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#
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:
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#
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:
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#
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 has the three ways out, the first being:
parity down --volumes
parity up
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#
[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#
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#
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:
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#
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
*,*/Nor a list for minute and hour, and*or a list for the rest. Write a range as a list (1,2,3,4,5, not1-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 setenvironmenttolocal,development,dev,testingortest.- An unknown field. A typo is caught rather than ignored. parity.json lists every field.
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#
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).