Madushan Pathirana
08/29/2025, 6:01 PMMarvin
08/29/2025, 6:01 PMMarvin
08/29/2025, 6:06 PMPREFECT_API_AUTH_STRING=admin:pass
.
- PREFECT_API_KEY
is only for Prefect Cloud and won’t work here.
- Docs: Server auth settings and API keys vs. basic auth.
2) The URL has angle brackets in it
- Your environment var includes <http://localhost:4200/api>
. The angle brackets will be treated as literal characters and break the URL. Use a plain URL with no brackets.
3) localhost vs container networking
- On Linux with --network host
, localhost
resolves to the host. On Docker Desktop (Windows/Mac/WSL2), --network host
does not behave the same and localhost
inside the container won’t reach services on the host. Use host.docker.internal
instead.
Try these fixes
A) First confirm the server is actually reachable from your host:
curl -i <http://localhost:4200/api/health>
You should get a 200 OK.
B) Then confirm the server is reachable from a container:
- On Windows/Mac/WSL2 (Docker Desktop):
docker run --rm curlimages/curl <http://host.docker.internal:4200/api/health>
- On Linux (not Docker Desktop), if you use host networking:
docker run --rm --network host curlimages/curl <http://127.0.0.1:4200/api/health>
C) Start your worker with the correct env vars and the right host value
- Windows/Mac/WSL2 (Docker Desktop):
docker run --rm \
-v /var/run/docker.sock:/var/run/docker.sock \
-e PREFECT_API_URL=<http://host.docker.internal:4200/api> \
-e PREFECT_API_AUTH_STRING=admin:pass \
prefect-worker-image \
prefect worker start -p my-docker-pool-2 --type docker
- Linux (native Docker, host networking):
docker run --rm \
--network host \
-v /var/run/docker.sock:/var/run/docker.sock \
-e PREFECT_API_URL=<http://127.0.0.1:4200/api> \
-e PREFECT_API_AUTH_STRING=admin:pass \
prefect-worker-image \
prefect worker start -p my-docker-pool-2 --type docker
Other checks
- Make sure the work pool exists and is of type docker. From a shell that can reach your server:
prefect work-pool ls
# or if needed:
prefect work-pool create my-docker-pool-2 --type docker
- Ensure the server was started with auth enabled and is using the same admin:pass
. If you started the server in a different environment (e.g., another container), you must pass PREFECT_SERVER_API_AUTH_STRING=admin:pass
to that process as well.
- Health check endpoint for the API is /api/health
. Docs: Self-hosted server.
If it still fails, please share:
- Your OS (Windows/Mac/Linux) and whether you’re using Docker Desktop or native Docker
- How you started the Prefect Server
- Output of:
- curl -i <http://localhost:4200/api/health>
on the host
- The docker run curlimages/curl .../health
test from above
We’ll get it sorted quickly from there.