Guides

Troubleshooting

The failures that do not say what they are, and what each one actually means.

Everything here has happened to us. They share a shape: the error message and the cause are in different parts of the system.

Reading the logs

Logs are structured, so grep for fields rather than for sentences:

journalctl -u shipkit-api -n 200 --no-pager
journalctl -u shipkit-worker -f

LOG_LEVEL=debug turns on a great deal more, including per-queue initialisation. Set it temporarily; leaving it on in production is how a disk fills.

Edit on GitHub

Internationalisation

Locale routing is wired and the catalogs are empty. What that means and what to do about it.

Auth

Better Auth with five plugins, a role column the API actually reads, and per-user scoping as the security boundary.

Troubleshooting

db:push fails with: type "vector" does not exist

Every auth request 404s at /api/api/auth/...

A correct password returns 'invalid credentials'

Login works, then the admin immediately bounces to /login

Sessions all record 127.0.0.1 as the client address

An enqueue hangs and the catch block never runs

Everything renders, but no emails and no webhooks go out

A CSS or env change does not appear after restarting

The build fails only on the build host, on the API

git push to a server checkout is rejected as 'dirty'

Reading the logs

On this page