Fawzi
08/11/2025, 11:48 AMMarvin
08/11/2025, 11:48 AMMarvin
08/11/2025, 11:52 AMprefect server stop
Notes and safe variants depending on how you started it:
- If you started background “services” with Prefect:
prefect server services ls
prefect server services stop
Then, if the API/webserver was also daemonized by Prefect:
prefect server stop
- If you ran prefect server start
in the foreground (e.g., in tmux/screen), stop it with Ctrl+C or by terminating that session. prefect server stop
only works for instances Prefect started in the background (it looks for a PID file under the same user).
- If you used a process manager, stop it there:
- systemd: sudo systemctl stop <your-prefect-server-service>
- Docker/Compose: docker compose down
(or docker stop <container>
)
Why this is “safest”: it lets Prefect shut down its API and services gracefully instead of you hunting PIDs.
Verified CLI references:
- prefect server stop
— Stop a Prefect server instance running in the background
- prefect server services stop
— Stop background services started by Prefect
- prefect server services ls
— See what’s running
Helpful docs:
- Host Prefect Server (2.x)
- Daemonize Prefect processes
- Prefect + Docker containers
If you tell me how you started the server (CLI foreground/background, systemd, Docker), I’ll give you the exact stop sequence. I know, thrilling.Fawzi
08/11/2025, 11:58 AMMarvin
08/11/2025, 11:58 AMMarvin
08/11/2025, 12:06 PMprefect server services ls
prefect server services stop
prefect server stop
2) Ensure no stray processes still have the DB open
- Check for lingering Prefect server processes (tmux/screen/systemd/docker) and stop them. Only one process should touch the SQLite file.
3) Clear stale SQLite lock files (after the server is fully stopped)
- If you see sidecar files next to your SQLite DB (typically ending with -wal
and -shm
), remove them. Do this only when you’re certain the server is not running.
4) Start the server and upgrade the schema (harmless if already current)
prefect server database upgrade
prefect server start
If you daemonize the server, start the services too:
prefect server services start
5) Restart workers and verify they connect to the right API and pool/queue
- Confirm worker environment has PREFECT_API_URL
pointing to your server.
- Double-check your queue/pool isn’t paused or constrained:
prefect work-pool ls
prefect work-pool inspect <pool-name>
prefect work-queue ls -p <pool-name>
prefect work-queue inspect <queue-name> -p <pool-name>
6) Re-run a small deployment and watch the worker logs
- If you still see “flow not found”, inspect the deployment’s entrypoint/source:
prefect deployment inspect "<flow-name>/<deployment-name>"
If your worker runs on a different machine, ensure the code is accessible to it (e.g., install your project as a package, or use a remote source like a Git repo or object storage instead of local paths).
If the lock returns or performance is poor
SQLite is fine for light, single-process use, but it does not handle concurrency well. For anything beyond light dev/test, switch to Postgres.
- Point Prefect to Postgres by setting this before starting the server:
export PREFECT_API_DATABASE_CONNECTION_URL="<postgresql+asyncpg://user:pass@host:5432/prefect>"
prefect server start
Make sure asyncpg
is installed in the server environment and the DB is reachable. This eliminates SQLite’s lock limitations. See: Host Prefect Server (2.x)
Other checks and edge cases
- Multiple servers: Ensure you didn’t accidentally start more than one Prefect server against the same SQLite file (tmux, systemd, Docker — it happens).
- Network filesystems: Don’t place the SQLite DB on NFS/SMB; file locking is unreliable there.
- Disk space/permissions: Low disk or permission issues can manifest as lock errors.
- Schema mismatch after updates: Running prefect server database upgrade
is safe.
- Last resort data wipe (development only):
prefect server database reset -y
This drops and recreates the Prefect DB — back up first.
Useful docs
- Host Prefect Server (2.x)
- Daemonize Prefect processes
- Related community issue showing SQLite pain points: Intermittent server 500s with SQLite
If you share:
- How you start the server (CLI, systemd, Docker)
- Whether you’re on SQLite or Postgres
- The worker’s logs around the failure
I’ll give you a tailored, step-by-step fix. I know, the excitement is palpable.