Short answer: your deployments/workers don’t “discover” your running server’s port. They use whatever API URL they’ve been configured with. If that URL points at a different host:port than your self‑hosted server, they’ll try to talk to the wrong place. Common causes and how to check/fix: - PREFECT_API_URL mismatch - The client (worker/job/flow code) connects to the API at

PREFECT_API_URL

(e.g., `http://127.0.0.1:4200/api`). If you changed the server’s port or host, but didn’t update this, you’ll see a mismatch. - Check what your environment is using:

prefect config view --show-sources

- Set it explicitly in your active profile:

prefect config set PREFECT_API_URL=<http://127.0.0.1:4200/api>

- Docs: Settings and profiles - Environment variable precedence and profiles - Environment variables override profile values. A stray

PREFECT_API_URL

in your shell, service unit, CI, or container image will win over your profile. - Use

prefect config view --show-sources

to see where a value is coming from (env vs profile vs default). - Work pool base job template overrides - For Docker/Kubernetes and other remote execution, the job’s environment can set

PREFECT_API_URL

in the base job template or worker configuration, overriding your local settings. - In the UI: Work Pools > your pool > Base job template > Environment variables; ensure

PREFECT_API_URL

matches your server. - If you baked a

.prefect/profiles.toml

into your image, that can also point jobs at a different API URL. - Localhost inside containers/pods -

localhost

inside a container/pod is the container/pod itself, not your host. If your server runs on your laptop at

<http://127.0.0.1:4200>

, a Docker/K8s job won’t reach it. - Options: - Bind the server to all interfaces and publish the port, then use your machine IP/hostname from the container:

prefect server start --host 0.0.0.0 --port 4200

and connect via

http://<your-host-ip>:4200/api

- For Docker on Mac/Windows,

<http://host.docker.internal:4200/api>

often works. - In Kubernetes, expose the server via a Service/Ingress and use the service DNS or external address. - Docs: Self-hosted Server (Docker) - You changed the server’s port but not clients - If you start the server on a custom port:

prefect server start --port 9000

make sure

PREFECT_API_URL

is updated everywhere to

http://<host>:9000/api

. - Wrong/old active profile (e.g., Cloud vs Server) - If you previously logged into Cloud, your active profile may still point at Cloud or another URL. Switch or update it:

prefect config view
    prefect config set PREFECT_API_URL=<http://127.0.0.1:4200/api>

Quick triage checklist: 1) On your machine:

prefect config view --show-sources

Confirm

PREFECT_API_URL

and its source. 2) On the worker host/container image, run the same command (or print env) to confirm it matches. 3) In your work pool’s base job template, remove or correct any

PREFECT_API_URL

env var. 4) If using containers/pods, ensure the URL points to a reachable host:port from that runtime (not localhost). If you can share: - The server command/port you’re using - Where your worker runs (local, Docker, K8s) and its

prefect config view

output for

PREFECT_API_URL

- Any env vars set in your work pool base job template …I can pinpoint exactly where the mismatch is coming from.

.serve

is like a process worker (a client side daemon), which polls the prefect server for work

ie the client-side work that happens in your

.serve

process cannot / should not be the same process as your

prefect server start

process