Prefect 3.7.6 - Scheduler State Fixes

Prefect 3.7.6 was published on June 25, 2026, for PrefectHQ/prefect. For data platform operators, the main fix is in MarkLateRuns: overdue flow runs should no longer take duplicate Late transitions when the scheduler service evaluates them. This is not a prerelease, so it belongs in the normal patch train for teams already running Prefect 3.x.

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

The scheduler change is narrow but operationally useful. PR #22316 prevents duplicate Late state transitions in MarkLateRuns, which means run history should show one late transition rather than repeated state churn for the same overdue run. For incident review, that removes noise around a basic question: did the run miss its window once, or did the scheduler keep recording the same fact?

The release also fixes a race condition in UI static directory creation when multiple workers are involved. The notes do not describe data loss or a database migration. They do point to a startup and file system race that can matter in container rollouts, where several workers can begin at the same time. That fix is in PR #22363.

Task.map now returns PrefectFutureList when deferred=True, via PR #22355. That matters when workflow code expects mapped task submission to return the same future collection shape in deferred execution. For ELT jobs, that is the difference between predictable downstream handling and special casing one branch of a fan out.

Prefect also now raises a clearer error when FlowRun or TaskRun is passed as a task argument, from PR #22352. That is not a new runtime capability. It is a better failure mode. Passing orchestration records through task parameters usually means the workflow is mixing control plane state with payload data, and a clear error helps stop that before it becomes a quiet serialization problem.

Several changes are documentation fixes, but they land in places that operators tend to copy into automation. The schedules page now uses canonical PREFECT_SERVER_SERVICES_SCHEDULER_* env vars in PR #22337. The systemd guide appends /api to self hosted PREFECT_API_URL in PR #22342. The Windows guide now uses canonical PREFECT_SERVER_DATABASE_* env vars in PR #22343, and the healthchecks guide uses canonical PREFECT_WORKER_* defaults in PR #22351.

There is also a documented CANCELLING timeout that moves stuck flow runs to CANCELLED, linked from PR #22305. That detail belongs in runbooks, because stuck cancellation is a common source of false active workload during maintenance. The release also notes that Redis Cluster URLs are not yet supported in self hosted setup, from PR #22370. That is a constraint to capture before changing cache or messaging topology.

For CLI users, work queue create output now quotes -q and -p separately. The fix in PR #22350 is small, but it affects copied commands and generated operator notes. In release automation, small quoting bugs can become confusing failures.

The development section is mostly test maintenance. Prefect widened timing tolerance in a lease TTL test and fixed a flaky cleanup and ack result test. That should not change runtime behavior for ETL jobs. It does say the project is reducing CI noise around timing and dispatch cleanup, which is useful context when deciding how much risk to assign to this patch.

The documentation generator also moved through mdxify updates and removed empty API ref stubs, with redirects for removed SDK stubs. For users, the practical result is cleaner reference navigation rather than a runtime change.