Short answer: there isn’t a built-in “max queue size” setting in Prefect. In Prefect 3.x you can cap how many runs execute at once, but not how many can be queued. What you can do instead - Cap parallelism (recommended baseline) - Work pool concurrency: limits total runs across the pool - Command:

prefect work-pool set-concurrency-limit <pool-name> <limit>

- Work queue concurrency: limits runs pulled from a specific queue - Command:

prefect work-queue set-concurrency-limit <queue-name> <limit> --pool <pool-name>

- Docs: Work pools and Rate limits and concurrency - Throttle the global start rate - Global concurrency limits provide a token-bucket style throttle for starting runs across your workspace - Command:

prefect global-concurrency-limit create <name> --limit <n> [--slot-decay-per-second <rate>]

- Docs: Rate limits and concurrency - Automatically pause when backlog grows (pattern) - Prefect does not expose a direct “backlog > N” switch, but you can implement backpressure with an automation or a small “watchdog” flow that: - counts flow runs on a queue in states like Scheduled/Pending/AwaitingConcurrencySlot - pauses the work queue (

prefect work-queue pause <queue> --pool <pool>

) or pauses deployment schedules when the count exceeds a threshold - resumes when it drops below the threshold - You can build this with Prefect Automations (e.g., a scheduled check that calls a webhook/CLI) or with a lightweight flow using the Prefect client. - Automations docs: Events and automations If you can share a bit more about your goal, I can suggest the cleanest setup: - Do you want to prevent new runs from being scheduled at all once N are already queued? - Or just ensure only N run concurrently? - Which worker infrastructure are you using (process, Docker, K8s)?

Great question — and the answer depends on the Prefect version you’re using. - In Prefect 3.x: there is no setting called

max_scheduled_queue_size

. The scheduler is controlled by server-side settings like: -

PREFECT_SERVER_SERVICES_SCHEDULER_MAX_RUNS

(default 100) -

PREFECT_SERVER_SERVICES_SCHEDULER_MIN_RUNS

(default 3) -

PREFECT_SERVER_SERVICES_SCHEDULER_MIN_SCHEDULED_TIME

(default 1h) -

PREFECT_SERVER_SERVICES_SCHEDULER_MAX_SCHEDULED_TIME

(default 100d) These determine how many future flow runs the server pre-materializes in the Scheduled state per deployment and how far into the future it looks — but they do not cap the work-queue backlog. They just control how many “future scheduled” runs exist in the database at any time. To change them on a self-hosted 3.x server, set environment variables on the server process or via your Prefect profile, e.g.:

prefect config set PREFECT_SERVER_SERVICES_SCHEDULER_MAX_RUNS=50
  prefect config set PREFECT_SERVER_SERVICES_SCHEDULER_MIN_RUNS=5

You can view current values with:

prefect config view --show-defaults

Settings reference: Settings reference - In Prefect 2.x: there was a similarly named setting (often referenced as

max_scheduled_queue_size

in older docs/threads). It served the same purpose: limit how many future runs the scheduler keeps “pre-scheduled” — not a hard cap on queue/backlog length. The modern 3.x equivalents are the settings above. Key points about how this works - It’s a server-side scheduler control for pre-creating future Scheduled runs, per deployment. - It does not prevent ad hoc/manual/API-triggered runs from being created. - It does not limit how many runs can be “waiting” in a work queue; for that, use concurrency controls: - Work pool limit:

prefect work-pool set-concurrency-limit <pool-name> <limit>

- Work queue limit:

prefect work-queue set-concurrency-limit <queue-name> <limit> --pool <pool-name>

Docs: Work pools and Rate limits and concurrency If you can share whether you’re on Prefect 2.x or 3.x (and whether you’re self-hosting the server), I can give exact steps for your environment.