What you’re seeing is expected with your current profile. Your config says:

bash
PREFECT_PROFILE='local'
PREFECT_API_URL='<http://127.0.0.1:4200/api>'

That means Prefect will always try to connect to a server already running at

127.0.0.1:4200

. If nothing is listening there, you’ll get:

text
RuntimeError: Failed to reach API at <http://127.0.0.1:4200/api/>

So the issue is less “mac vs linux” and more: your Mac is using a

local

profile pointed at a persistent local server, not ephemeral mode. How to fix it You have two valid setups: Option 1: Use ephemeral mode for local development This is the easiest if you want to “just run it” without manually starting a server. Switch to the built-in

ephemeral

profile:

bash
uv run prefect profile use ephemeral
uv run prefect config view

You should then see no

PREFECT_API_URL

, and ephemeral mode enabled instead. If you want to confirm available profile commands, Prefect CLI supports: Settings and profiles If you have an old

~/.prefect/profiles.toml

overriding defaults, that can interfere. Check it:

bash
cat ~/.prefect/profiles.toml

You want the active profile to not force:

toml
PREFECT_API_URL = "<http://127.0.0.1:4200/api>"

If you want, you can create a fresh dev profile based on ephemeral behavior instead of using

local

. Option 2: Keep using the local server profile If you want

PREFECT_API_URL=<http://127.0.0.1:4200/api>

, then you must run:

bash
uv run prefect server start

That profile is for a manually managed local API server. Why the test harness works The test harness typically enables an in-process or ephemeral test API, so it doesn’t depend on a standalone server already running on port 4200. What I recommend If your goal is “run flows locally without thinking about the API,” do this:

bash
uv run prefect profile use ephemeral

Then retry your flow. If it still fails on macOS after switching to

ephemeral

, check these:

bash
uv run prefect config view
ls -la ~/.prefect/profiles.toml
lsof -i :4200

Also make sure you don’t have an environment variable overriding the profile:

bash
echo $PREFECT_API_URL

If that prints

<http://127.0.0.1:4200/api>

, unset it:

bash
unset PREFECT_API_URL

In short -

local

profile +

PREFECT_API_URL=<http://127.0.0.1:4200/api>

=> requires

prefect server start

-

ephemeral

profile => should let you just run flows locally without manually starting a server If you want, I can help you inspect your

~/.prefect/profiles.toml

and tell you exactly what to change.