Yes — there are compatibility rules. Short version: - Self-hosted Prefect server/API: worker and server should be on the same major version - Prefect Cloud: version checks are skipped, so this is generally not something you need to manage directly - Within the same major version, minor/patch mismatches may work, but newer workers against older self-hosted servers can cause warnings or unexpected behavior Rules of thumb 1. Major versions must match for self-hosted server - Prefect 3.x workers should talk to a Prefect 3.x server - Prefect 2.x workers should not talk to a 3.x server, and vice versa 2. Minor/patch mismatches are softer - Usually okay within 3.x - But if the worker is newer than the server, Prefect may warn that behavior could be unexpected - Best practice: keep them as close as possible 3. Prefect Cloud is different - Cloud skips the server-version compatibility check - In practice, you generally just keep your worker reasonably up to date 4. Best practice for self-hosted upgrades - Upgrade the server first - Then upgrade workers Practical recommendation - If you're self-hosting: run the same Prefect version on server and workers whenever possible - If exact match is hard: at least stay on the same major version, and avoid workers being far ahead of the server How to check versions Worker version:

bash
python -c "import prefect; print(prefect.__version__)"

If you want, I can also give you a compatibility matrix / upgrade playbook for: - self-hosted server + workers - Prefect Cloud + workers - mixed worker fleets during rolling upgrades

Here’s a practical self-hosted Prefect server + worker compatibility matrix for Prefect 3.x. Compatibility matrix | Server | Worker | Status | Notes | |---|---|---|---| | 3.x | 3.x same version | Best / recommended | Safest choice | | 3.x | 3.x different patch | Usually OK | Prefer keeping close | | 3.x | 3.x different minor | Usually OK with caution | Newer worker vs older server may warn / behave unexpectedly | | 3.x | 2.x | Not compatible | Major versions must match | | 2.x | 3.x | Not compatible | Major versions must match | | 4.x | 3.x | Not compatible | Major versions must match | More detailed matrix | Self-hosted server | Worker | Expected result | |---|---|---| | 3.7.0 | 3.7.0 | Fully compatible | | 3.7.0 | 3.7.2 | Compatible | | 3.7.2 | 3.7.0 | Compatible | | 3.7.0 | 3.6.5 | Usually compatible | | 3.6.5 | 3.7.0 | Usually compatible, but worker may warn if newer than server | | 3.5.x | 3.7.x | May work, but more risk | | 3.x | 2.x | Fails | | 2.x | 3.x | Fails | Operational guidance - Best: pin server and workers to the exact same version - Acceptable: same major version, close minor/patch versions - Avoid: workers significantly newer than the server - Never: cross-major connections Upgrade order 1. Upgrade server 2. Verify API is healthy 3. Upgrade workers 4. Restart workers gradually if doing a rolling upgrade This order reduces the risk of newer workers talking to older server code. Rolling upgrade advice If you have many workers: - temporarily mixing

3.6.x

and

3.7.x

workers against a

3.7.x

server is generally safer than the reverse - keep the mixed-version window short - watch worker logs for version warnings or websocket/connectivity issues Recommended policy A good policy for self-hosted environments is: - Required: same major version - Target: exact same version - Allowed temporarily: same major, within 1 minor version during upgrades How to verify worker version

bash
python -c "import prefect; print(prefect.__version__)"

If you want, I can also turn this into: - a one-line upgrade policy for your team docs, or - a Helm/Docker deployment strategy for keeping server and workers aligned.