Prefect 3.8.4 - Worker Polling And Run Outcome Fixes

Prefect 3.8.4 shipped on 25 August 2026. The tag is a normal patch, not a prerelease. The change that operators should read first is that runners no longer overwrite flow run outcomes the API already handled, which is a state correctness bug on any worker that retries or races a terminal write.

The full release notes and downloads are on the GitHub release page.

#22821 stops runners from overwriting handled flow run outcomes. Once the API has recorded a terminal result, a late runner write must not replace it. The usual symptom is a run that already completed or failed flipping to another state when a process exits after the server applied the result.

BaseWorker now honors a prefetch_seconds of 0 (#22836). Setting 0 is how you disable lookahead. Before this patch that value was not treated as a real configuration, so workers still pulled work early. Zero now means zero.

The worker polling healthcheck now uses total_seconds (#22900). Operators who alert on worker poll freshness should confirm the healthcheck still matches the poll interval they configured. A duration stored as a timedelta and then read as a clock field is a common source of false healthy or false unhealthy signals.

ProcessWorker also got a fix for auto-uv after pull steps (#22857). If a deployment pull step rewrites the working tree and the worker then tries to run with uv, that path was broken. The bug is specific to ProcessWorker after pull steps, not to image based workers that never pull source at runtime.

Self hosted Prefect APIs get a new index on flow_run.deployment_id (#22890). Queries that filter or join flow runs by deployment can use it instead of scanning a large flow_run table. Expect a schema apply on upgrade. On a busy metadata database that index build is the part of the patch that can take wall clock time. The notes do not document a lock strategy, so run the upgrade against a copy of production metadata if that table is large.

Interval schedules now accept a time on the anchor date (#22872). The anchor used to be a date. If a flow should fire every N hours from a wall clock time, that extra field is the missing piece. Check deployments that already encode the time in a cron string before you rewrite them as interval schedules.

#22855 adds a configurable base directory for included files. Deployment packaging that ships a subset of a repo can point that include root at a subdirectory instead of the checkout root. That is the useful path when flow code lives under a nested tree and the rest of the repo should stay out of the bundle.

The UI also opens a parameters dialog when a quick run needs required parameters (#22903). That is a console change, not a scheduler change.

Two Dockerfile fixes bind mount the sdist during the image build so it does not ship in the published image. #22832 covers the main image. #22833 does the same in client/Dockerfile. The image still installs the package. It stops leaving the sdist on disk. If you scan Prefect images for leftover source distributions, those copies should be gone after this tag.

Docs add new Prefect Managed outbound IPs (#22934). If workers or webhooks in a Prefect Managed workspace must reach your network, update the allowlist from that doc change. The release text does not print the IP list, so read the docs, not this post, for the addresses.

The rest of the tag is internal. CodeQL follows v4 releases. Tests split with pytest-split on Python 3.12 Postgres, gain opt in Logfire profiling, and stop depending on ambient OpenTelemetry context or leftover PREFECT_ env vars. Several e2e tests were scoped more tightly to kill flakes. None of that changes runtime behavior. V2 UI fixes for lateness labels, run durations, seconds that round up into larger units, invisible graph nodes (skipUpdateTransform=false), and deployment status on the flow detail page stay in the console. They do not change the API.

No breaking change is listed. Self hosted APIs still apply the new flow_run.deployment_id index on upgrade. Run that against a copy of production metadata if the flow_run table is large. Image users who pin by digest should pull the new tags after the sdist bind mount fixes. Compare 3.8.3 to 3.8.4 on the GitHub changelog if you need the full commit list.