ContextQMD
Back to Prefect

Settings reference

docs/v3/api-ref/settings-ref.mdx

3.6.30.dev384.6 KB
Original Source

<Note>To use prefect.toml or pyproject.toml for configuration, prefect>=3.1 must be installed.</Note>

Root Settings

home

The path to the Prefect home directory. Defaults to ~/.prefect

Type: string

Default: ~/.prefect

TOML dotted key path: home

Supported environment variables: PREFECT_HOME

profiles_path

The path to a profiles configuration file. Supports $PREFECT_HOME templating. Defaults to $PREFECT_HOME/profiles.toml.

Type: string

TOML dotted key path: profiles_path

Supported environment variables: PREFECT_PROFILES_PATH

debug_mode

If True, enables debug mode which may provide additional logging and debugging features.

Type: boolean

Default: False

TOML dotted key path: debug_mode

Supported environment variables: PREFECT_DEBUG_MODE

api

Type: APISettings

TOML dotted key path: api

cli

Type: CLISettings

TOML dotted key path: cli

client

Type: ClientSettings

TOML dotted key path: client

cloud

Type: CloudSettings

TOML dotted key path: cloud

deployments

Type: DeploymentsSettings

TOML dotted key path: deployments

events

Type: EventsSettings

TOML dotted key path: events

experiments

Settings for controlling experimental features

Type: ExperimentsSettings

TOML dotted key path: experiments

flows

Type: FlowsSettings

TOML dotted key path: flows

internal

Settings for internal Prefect machinery

Type: InternalSettings

TOML dotted key path: internal

logging

Type: LoggingSettings

TOML dotted key path: logging

results

Type: ResultsSettings

TOML dotted key path: results

runner

Type: RunnerSettings

TOML dotted key path: runner

server

Type: ServerSettings

TOML dotted key path: server

tasks

Settings for controlling task behavior

Type: TasksSettings

TOML dotted key path: tasks

telemetry

Settings for configuring telemetry collection

Type: TelemetrySettings

TOML dotted key path: telemetry

testing

Settings used during testing

Type: TestingSettings

TOML dotted key path: testing

worker

Settings for controlling worker behavior

Type: WorkerSettings

TOML dotted key path: worker

ui_url

The URL of the Prefect UI. If not set, the client will attempt to infer it.

Type: string | None

Default: None

TOML dotted key path: ui_url

Supported environment variables: PREFECT_UI_URL

silence_api_url_misconfiguration

    If `True`, disable the warning when a user accidentally misconfigure its `PREFECT_API_URL`
    Sometimes when a user manually set `PREFECT_API_URL` to a custom url,reverse-proxy for example,
    we would like to silence this warning so we will set it to `FALSE`.

Type: boolean

Default: False

TOML dotted key path: silence_api_url_misconfiguration

Supported environment variables: PREFECT_SILENCE_API_URL_MISCONFIGURATION

APISettings

Settings for interacting with the Prefect API

url

The URL of the Prefect API. If not set, the client will attempt to infer it.

Type: string | None

Default: None

TOML dotted key path: api.url

Supported environment variables: PREFECT_API_URL

auth_string

The auth string used for basic authentication with a self-hosted Prefect API. Should be kept secret.

Type: string | None

Default: None

TOML dotted key path: api.auth_string

Supported environment variables: PREFECT_API_AUTH_STRING

key

The API key used for authentication with the Prefect API. Should be kept secret.

Type: string | None

Default: None

TOML dotted key path: api.key

Supported environment variables: PREFECT_API_KEY

tls_insecure_skip_verify

If True, disables SSL checking to allow insecure requests. Setting to False is recommended only during development. For example, when using self-signed certificates.

Type: boolean

Default: False

TOML dotted key path: api.tls_insecure_skip_verify

Supported environment variables: PREFECT_API_TLS_INSECURE_SKIP_VERIFY

ssl_cert_file

This configuration settings option specifies the path to an SSL certificate file.

Type: string | None

Default: None

TOML dotted key path: api.ssl_cert_file

Supported environment variables: PREFECT_API_SSL_CERT_FILE

enable_http2

If true, enable support for HTTP/2 for communicating with an API. If the API does not support HTTP/2, this will have no effect and connections will be made via HTTP/1.1.

Type: boolean

Default: False

TOML dotted key path: api.enable_http2

Supported environment variables: PREFECT_API_ENABLE_HTTP2

request_timeout

The default timeout for requests to the API

Type: number

Default: 60.0

TOML dotted key path: api.request_timeout

Supported environment variables: PREFECT_API_REQUEST_TIMEOUT

CLISettings

Settings for controlling CLI behavior

colors

If True, use colors in CLI output. If False, output will not include colors codes.

Type: boolean

Default: True

TOML dotted key path: cli.colors

Supported environment variables: PREFECT_CLI_COLORS

prompt

If True, use interactive prompts in CLI commands. If False, no interactive prompts will be used. If None, the value will be dynamically determined based on the presence of an interactive-enabled terminal.

Type: boolean | None

Default: None

TOML dotted key path: cli.prompt

Supported environment variables: PREFECT_CLI_PROMPT

wrap_lines

If True, wrap text by inserting new lines in long lines in CLI output. If False, output will not be wrapped.

Type: boolean

Default: True

TOML dotted key path: cli.wrap_lines

Supported environment variables: PREFECT_CLI_WRAP_LINES

ClientMetricsSettings

Settings for controlling metrics reporting from the client

enabled

Whether or not to enable Prometheus metrics in the client.

Type: boolean

Default: False

TOML dotted key path: client.metrics.enabled

Supported environment variables: PREFECT_CLIENT_METRICS_ENABLED, PREFECT_CLIENT_ENABLE_METRICS

port

The port to expose the client Prometheus metrics on.

Type: integer

Default: 4201

TOML dotted key path: client.metrics.port

Supported environment variables: PREFECT_CLIENT_METRICS_PORT

ClientSettings

Settings for controlling API client behavior

max_retries

    The maximum number of retries to perform on failed HTTP requests.
    Defaults to 5. Set to 0 to disable retries.
    See `PREFECT_CLIENT_RETRY_EXTRA_CODES` for details on which HTTP status codes are
    retried.

Type: integer

Default: 5

Constraints:

  • Minimum: 0

TOML dotted key path: client.max_retries

Supported environment variables: PREFECT_CLIENT_MAX_RETRIES

retry_jitter_factor

    A value greater than or equal to zero to control the amount of jitter added to retried
    client requests. Higher values introduce larger amounts of jitter.
    Set to 0 to disable jitter. See `clamped_poisson_interval` for details on the how jitter
    can affect retry lengths.

Type: number

Default: 0.2

Constraints:

  • Minimum: 0.0

TOML dotted key path: client.retry_jitter_factor

Supported environment variables: PREFECT_CLIENT_RETRY_JITTER_FACTOR

retry_extra_codes

    A list of extra HTTP status codes to retry on. Defaults to an empty list.
    429, 502 and 503 are always retried. Please note that not all routes are idempotent and retrying
    may result in unexpected behavior.

Type: string | integer | array | None

Examples:

  • "404,429,503"
  • "429"
  • [404, 429, 503]

TOML dotted key path: client.retry_extra_codes

Supported environment variables: PREFECT_CLIENT_RETRY_EXTRA_CODES

csrf_support_enabled

    Determines if CSRF token handling is active in the Prefect client for API
    requests.

    When enabled (`True`), the client automatically manages CSRF tokens by
    retrieving, storing, and including them in applicable state-changing requests

Type: boolean

Default: True

TOML dotted key path: client.csrf_support_enabled

Supported environment variables: PREFECT_CLIENT_CSRF_SUPPORT_ENABLED

custom_headers

    Custom HTTP headers to include with every API request to the Prefect server.
    Headers are specified as key-value pairs. Note that headers like 'User-Agent'
    and CSRF-related headers are managed by Prefect and cannot be overridden.

Type: object

Examples:

  • {'X-Custom-Header': 'value'}
  • {'Authorization': 'Bearer token'}

TOML dotted key path: client.custom_headers

Supported environment variables: PREFECT_CLIENT_CUSTOM_HEADERS

server_version_check_enabled

    Whether the client should check the server's API version on startup.
    When disabled, the client will skip the call to /admin/version that
    normally runs once per client context entry.  This is useful for worker
    subprocesses that inherit a known-compatible server configuration and
    do not need to repeat the version handshake.

Type: boolean

Default: True

TOML dotted key path: client.server_version_check_enabled

Supported environment variables: PREFECT_CLIENT_SERVER_VERSION_CHECK_ENABLED

metrics

Type: ClientMetricsSettings

TOML dotted key path: client.metrics

CloudSettings

Settings for interacting with Prefect Cloud

api_url

API URL for Prefect Cloud. Used for authentication with Prefect Cloud.

Type: string

Default: https://api.prefect.cloud/api

TOML dotted key path: cloud.api_url

Supported environment variables: PREFECT_CLOUD_API_URL

enable_orchestration_telemetry

Whether or not to enable orchestration telemetry.

Type: boolean

Default: True

TOML dotted key path: cloud.enable_orchestration_telemetry

Supported environment variables: PREFECT_CLOUD_ENABLE_ORCHESTRATION_TELEMETRY

max_log_size

Maximum size in characters for a single log when sending logs to Prefect Cloud.

Type: integer

Default: 25000

TOML dotted key path: cloud.max_log_size

Supported environment variables: PREFECT_CLOUD_MAX_LOG_SIZE

ui_url

The URL of the Prefect Cloud UI. If not set, the client will attempt to infer it.

Type: string | None

Default: None

TOML dotted key path: cloud.ui_url

Supported environment variables: PREFECT_CLOUD_UI_URL

DeploymentsSettings

Settings for configuring deployments defaults

default_work_pool_name

The default work pool to use when creating deployments.

Type: string | None

Default: None

TOML dotted key path: deployments.default_work_pool_name

Supported environment variables: PREFECT_DEPLOYMENTS_DEFAULT_WORK_POOL_NAME, PREFECT_DEFAULT_WORK_POOL_NAME

default_docker_build_namespace

The default Docker namespace to use when building images.

Type: string | None

Default: None

Examples:

  • "my-dockerhub-registry"
  • "4999999999999.dkr.ecr.us-east-2.amazonaws.com/my-ecr-repo"

TOML dotted key path: deployments.default_docker_build_namespace

Supported environment variables: PREFECT_DEPLOYMENTS_DEFAULT_DOCKER_BUILD_NAMESPACE, PREFECT_DEFAULT_DOCKER_BUILD_NAMESPACE

EventsSettings

Settings for controlling events behavior

worker_max_queue_size

    Maximum number of events that can be queued for delivery to the
    Prefect server. When the queue is full, new events are dropped with
    a warning. Set to 0 for unbounded (the default).

    Warning: setting this value too low may result in data loss as events
    will be silently dropped when the queue is full.

Type: integer

Default: 0

Constraints:

  • Minimum: 0

TOML dotted key path: events.worker_max_queue_size

Supported environment variables: PREFECT_EVENTS_WORKER_MAX_QUEUE_SIZE

ExperimentsSettings

Settings for configuring experimental features

warn

If True, warn on usage of experimental features.

Type: boolean

Default: True

TOML dotted key path: experiments.warn

Supported environment variables: PREFECT_EXPERIMENTS_WARN, PREFECT_EXPERIMENTAL_WARN

plugins

Settings for the experimental plugin system

Type: PluginsSettings

TOML dotted key path: experiments.plugins

FlowsSettings

Settings for controlling flow behavior

heartbeat_frequency

Number of seconds between flow run heartbeats. Heartbeats are used to detect crashed flow runs.

Type: integer | None

Default: 180

TOML dotted key path: flows.heartbeat_frequency

Supported environment variables: PREFECT_FLOWS_HEARTBEAT_FREQUENCY, PREFECT_RUNNER_HEARTBEAT_FREQUENCY

default_retries

This value sets the default number of retries for all flows.

Type: integer

Default: 0

Constraints:

  • Minimum: 0

TOML dotted key path: flows.default_retries

Supported environment variables: PREFECT_FLOWS_DEFAULT_RETRIES, PREFECT_FLOW_DEFAULT_RETRIES

default_retry_delay_seconds

This value sets the default retry delay seconds for all flows.

Type: integer | number | array

Default: 0

TOML dotted key path: flows.default_retry_delay_seconds

Supported environment variables: PREFECT_FLOWS_DEFAULT_RETRY_DELAY_SECONDS, PREFECT_FLOW_DEFAULT_RETRY_DELAY_SECONDS

InternalSettings

logging_level

The default logging level for Prefect's internal machinery loggers.

Type: string

Default: ERROR

Constraints:

  • Allowed values: 'DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'

TOML dotted key path: internal.logging_level

Supported environment variables: PREFECT_INTERNAL_LOGGING_LEVEL, PREFECT_LOGGING_INTERNAL_LEVEL

LoggingSettings

Settings for controlling logging behavior

level

The default logging level for Prefect loggers.

Type: string

Default: INFO

Constraints:

  • Allowed values: 'DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'

TOML dotted key path: logging.level

Supported environment variables: PREFECT_LOGGING_LEVEL

config_path

A path to a logging configuration file. Defaults to $PREFECT_HOME/logging.yml

Type: string

TOML dotted key path: logging.config_path

Supported environment variables: PREFECT_LOGGING_CONFIG_PATH, PREFECT_LOGGING_SETTINGS_PATH

extra_loggers

Additional loggers to attach to Prefect logging at runtime.

Type: string | array | None

Default: None

TOML dotted key path: logging.extra_loggers

Supported environment variables: PREFECT_LOGGING_EXTRA_LOGGERS

log_prints

If True, print statements in flows and tasks will be redirected to the Prefect logger for the given run.

Type: boolean

Default: False

TOML dotted key path: logging.log_prints

Supported environment variables: PREFECT_LOGGING_LOG_PRINTS

colors

If True, use colors in CLI output. If False, output will not include colors codes.

Type: boolean

Default: True

TOML dotted key path: logging.colors

Supported environment variables: PREFECT_LOGGING_COLORS

markup

    Whether to interpret strings wrapped in square brackets as a style.
    This allows styles to be conveniently added to log messages, e.g.
    `[red]This is a red message.[/red]`. However, the downside is, if enabled,
    strings that contain square brackets may be inaccurately interpreted and
    lead to incomplete output, e.g.
    `[red]This is a red message.[/red]` may be interpreted as
    `[red]This is a red message.[/red]`.

Type: boolean

Default: False

TOML dotted key path: logging.markup

Supported environment variables: PREFECT_LOGGING_MARKUP

to_api

Type: LoggingToAPISettings

TOML dotted key path: logging.to_api

LoggingToAPISettings

Settings for controlling logging to the API

enabled

If True, logs will be sent to the API.

Type: boolean

Default: True

TOML dotted key path: logging.to_api.enabled

Supported environment variables: PREFECT_LOGGING_TO_API_ENABLED

batch_interval

The number of seconds between batched writes of logs to the API.

Type: number

Default: 2.0

TOML dotted key path: logging.to_api.batch_interval

Supported environment variables: PREFECT_LOGGING_TO_API_BATCH_INTERVAL

batch_size

The number of logs to batch before sending to the API.

Type: integer

Default: 4000000

TOML dotted key path: logging.to_api.batch_size

Supported environment variables: PREFECT_LOGGING_TO_API_BATCH_SIZE

max_log_size

The maximum size in characters for a single log. When connected to Prefect Cloud, this value is capped at PREFECT_CLOUD_MAX_LOG_SIZE (default 25,000).

Type: integer

Default: 1000000

TOML dotted key path: logging.to_api.max_log_size

Supported environment variables: PREFECT_LOGGING_TO_API_MAX_LOG_SIZE

when_missing_flow

    Controls the behavior when loggers attempt to send logs to the API handler from outside of a flow.
    
    All logs sent to the API must be associated with a flow run. The API log handler can
    only be used outside of a flow by manually providing a flow run identifier. Logs
    that are not associated with a flow run will not be sent to the API. This setting can
    be used to determine if a warning or error is displayed when the identifier is missing.

    The following options are available:

    - "warn": Log a warning message.
    - "error": Raise an error.
    - "ignore": Do not log a warning message or raise an error.

Type: string

Default: warn

Constraints:

  • Allowed values: 'warn', 'error', 'ignore'

TOML dotted key path: logging.to_api.when_missing_flow

Supported environment variables: PREFECT_LOGGING_TO_API_WHEN_MISSING_FLOW

PluginsSettings

Settings for configuring the experimental plugin system

enabled

Enable the experimental plugin system.

Type: boolean

Default: False

TOML dotted key path: experiments.plugins.enabled

Supported environment variables: PREFECT_EXPERIMENTS_PLUGINS_ENABLED

allow

Comma-separated list of plugin names to allow. If set, only these plugins will be loaded.

Type: array | None

Default: None

TOML dotted key path: experiments.plugins.allow

Supported environment variables: PREFECT_EXPERIMENTS_PLUGINS_ALLOW

deny

Comma-separated list of plugin names to deny. These plugins will not be loaded.

Type: array | None

Default: None

TOML dotted key path: experiments.plugins.deny

Supported environment variables: PREFECT_EXPERIMENTS_PLUGINS_DENY

setup_timeout_seconds

Maximum time in seconds for all plugins to complete their setup hooks.

Type: number

Default: 20.0

TOML dotted key path: experiments.plugins.setup_timeout_seconds

Supported environment variables: PREFECT_EXPERIMENTS_PLUGINS_SETUP_TIMEOUT_SECONDS

strict

If True, exit if a required plugin fails during setup.

Type: boolean

Default: False

TOML dotted key path: experiments.plugins.strict

Supported environment variables: PREFECT_EXPERIMENTS_PLUGINS_STRICT

safe_mode

If True, load plugins but do not execute their hooks. Useful for testing.

Type: boolean

Default: False

TOML dotted key path: experiments.plugins.safe_mode

Supported environment variables: PREFECT_EXPERIMENTS_PLUGINS_SAFE_MODE

ResultsSettings

Settings for controlling result storage behavior

default_serializer

The default serializer to use when not otherwise specified.

Type: string

Default: pickle

TOML dotted key path: results.default_serializer

Supported environment variables: PREFECT_RESULTS_DEFAULT_SERIALIZER

persist_by_default

The default setting for persisting results when not otherwise specified.

Type: boolean

Default: False

TOML dotted key path: results.persist_by_default

Supported environment variables: PREFECT_RESULTS_PERSIST_BY_DEFAULT

default_storage_block

The block-type/block-document slug of a block to use as the default result storage.

Type: string | None

Default: None

TOML dotted key path: results.default_storage_block

Supported environment variables: PREFECT_RESULTS_DEFAULT_STORAGE_BLOCK, PREFECT_DEFAULT_RESULT_STORAGE_BLOCK

local_storage_path

The default location for locally persisted results. Defaults to $PREFECT_HOME/storage.

Type: string

TOML dotted key path: results.local_storage_path

Supported environment variables: PREFECT_RESULTS_LOCAL_STORAGE_PATH, PREFECT_LOCAL_STORAGE_PATH

RunnerServerSettings

Settings for controlling runner server behavior

enable

Whether or not to enable the runner's webserver.

Type: boolean

Default: False

TOML dotted key path: runner.server.enable

Supported environment variables: PREFECT_RUNNER_SERVER_ENABLE

host

The host address the runner's webserver should bind to.

Type: string

Default: localhost

TOML dotted key path: runner.server.host

Supported environment variables: PREFECT_RUNNER_SERVER_HOST

port

The port the runner's webserver should bind to.

Type: integer

Default: 8080

TOML dotted key path: runner.server.port

Supported environment variables: PREFECT_RUNNER_SERVER_PORT

log_level

The log level of the runner's webserver.

Type: string

Default: ERROR

Constraints:

  • Allowed values: 'DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'

TOML dotted key path: runner.server.log_level

Supported environment variables: PREFECT_RUNNER_SERVER_LOG_LEVEL

missed_polls_tolerance

Number of missed polls before a runner is considered unhealthy by its webserver.

Type: integer

Default: 2

TOML dotted key path: runner.server.missed_polls_tolerance

Supported environment variables: PREFECT_RUNNER_SERVER_MISSED_POLLS_TOLERANCE

RunnerSettings

Settings for controlling runner behavior

process_limit

Maximum number of processes a runner will execute in parallel.

Type: integer

Default: 5

TOML dotted key path: runner.process_limit

Supported environment variables: PREFECT_RUNNER_PROCESS_LIMIT

poll_frequency

Number of seconds a runner should wait between queries for scheduled work.

Type: integer

Default: 10

TOML dotted key path: runner.poll_frequency

Supported environment variables: PREFECT_RUNNER_POLL_FREQUENCY

crash_on_cancellation_failure

Whether to crash flow runs and shut down the runner when cancellation observing fails. When enabled, if both websocket and polling mechanisms for detecting cancellation events fail, all in-flight flow runs will be marked as crashed and the runner will shut down. When disabled (default), the runner will log an error but continue executing flow runs.

Type: boolean

Default: False

TOML dotted key path: runner.crash_on_cancellation_failure

Supported environment variables: PREFECT_RUNNER_CRASH_ON_CANCELLATION_FAILURE

server

Type: RunnerServerSettings

TOML dotted key path: runner.server

SQLAlchemyConnectArgsSettings

Settings for controlling SQLAlchemy connection behavior; note that these settings only take effect when using a PostgreSQL database.

application_name

Controls the application_name field for connections opened from the connection pool when using a PostgreSQL database with the Prefect backend.

Type: string | None

Default: None

TOML dotted key path: server.database.sqlalchemy.connect_args.application_name

Supported environment variables: PREFECT_SERVER_DATABASE_SQLALCHEMY_CONNECT_ARGS_APPLICATION_NAME

search_path

PostgreSQL schema name to set in search_path when using a PostgreSQL database with the Prefect backend. Note: The public schema should be included in the search path (e.g. 'myschema, public') to ensure that pg_trgm and other extensions remain available.

Type: string | None

Default: None

TOML dotted key path: server.database.sqlalchemy.connect_args.search_path

Supported environment variables: PREFECT_SERVER_DATABASE_SQLALCHEMY_CONNECT_ARGS_SEARCH_PATH

statement_cache_size

Controls statement cache size for PostgreSQL connections. Setting this to 0 is required when using PgBouncer in transaction mode. Defaults to None.

Type: integer | None

Default: None

TOML dotted key path: server.database.sqlalchemy.connect_args.statement_cache_size

Supported environment variables: PREFECT_SERVER_DATABASE_SQLALCHEMY_CONNECT_ARGS_STATEMENT_CACHE_SIZE

prepared_statement_cache_size

Controls the size of the statement cache for PostgreSQL connections. When set to 0, statement caching is disabled. Defaults to None to use SQLAlchemy's default behavior.

Type: integer | None

Default: None

TOML dotted key path: server.database.sqlalchemy.connect_args.prepared_statement_cache_size

Supported environment variables: PREFECT_SERVER_DATABASE_SQLALCHEMY_CONNECT_ARGS_PREPARED_STATEMENT_CACHE_SIZE

tls

Settings for controlling SQLAlchemy mTLS behavior

Type: SQLAlchemyTLSSettings

TOML dotted key path: server.database.sqlalchemy.connect_args.tls

SQLAlchemySettings

Settings for controlling SQLAlchemy behavior; note that these settings only take effect when using a PostgreSQL database.

connect_args

Settings for controlling SQLAlchemy connection behavior

Type: SQLAlchemyConnectArgsSettings

TOML dotted key path: server.database.sqlalchemy.connect_args

pool_size

Controls connection pool size of database connection pools from the Prefect backend.

Type: integer

Default: 5

TOML dotted key path: server.database.sqlalchemy.pool_size

Supported environment variables: PREFECT_SERVER_DATABASE_SQLALCHEMY_POOL_SIZE, PREFECT_SQLALCHEMY_POOL_SIZE

pool_recycle

This setting causes the pool to recycle connections after the given number of seconds has passed; set it to -1 to avoid recycling entirely.

Type: integer

Default: 3600

TOML dotted key path: server.database.sqlalchemy.pool_recycle

Supported environment variables: PREFECT_SERVER_DATABASE_SQLALCHEMY_POOL_RECYCLE

pool_timeout

Number of seconds to wait before giving up on getting a connection from the pool. Defaults to 30 seconds.

Type: number | None

Default: 30.0

TOML dotted key path: server.database.sqlalchemy.pool_timeout

Supported environment variables: PREFECT_SERVER_DATABASE_SQLALCHEMY_POOL_TIMEOUT

max_overflow

Controls maximum overflow of the connection pool. To prevent overflow, set to -1.

Type: integer

Default: 10

TOML dotted key path: server.database.sqlalchemy.max_overflow

Supported environment variables: PREFECT_SERVER_DATABASE_SQLALCHEMY_MAX_OVERFLOW, PREFECT_SQLALCHEMY_MAX_OVERFLOW

SQLAlchemyTLSSettings

Settings for controlling SQLAlchemy mTLS context when using a PostgreSQL database.

enabled

Controls whether connected to mTLS enabled PostgreSQL when using a PostgreSQL database with the Prefect backend.

Type: boolean

Default: False

TOML dotted key path: server.database.sqlalchemy.connect_args.tls.enabled

Supported environment variables: PREFECT_SERVER_DATABASE_SQLALCHEMY_CONNECT_ARGS_TLS_ENABLED

ca_file

This configuration settings option specifies the path to PostgreSQL client certificate authority file.

Type: string | None

Default: None

TOML dotted key path: server.database.sqlalchemy.connect_args.tls.ca_file

Supported environment variables: PREFECT_SERVER_DATABASE_SQLALCHEMY_CONNECT_ARGS_TLS_CA_FILE

cert_file

This configuration settings option specifies the path to PostgreSQL client certificate file.

Type: string | None

Default: None

TOML dotted key path: server.database.sqlalchemy.connect_args.tls.cert_file

Supported environment variables: PREFECT_SERVER_DATABASE_SQLALCHEMY_CONNECT_ARGS_TLS_CERT_FILE

key_file

This configuration settings option specifies the path to PostgreSQL client key file.

Type: string | None

Default: None

TOML dotted key path: server.database.sqlalchemy.connect_args.tls.key_file

Supported environment variables: PREFECT_SERVER_DATABASE_SQLALCHEMY_CONNECT_ARGS_TLS_KEY_FILE

check_hostname

This configuration settings option specifies whether to verify PostgreSQL server hostname.

Type: boolean

Default: True

TOML dotted key path: server.database.sqlalchemy.connect_args.tls.check_hostname

Supported environment variables: PREFECT_SERVER_DATABASE_SQLALCHEMY_CONNECT_ARGS_TLS_CHECK_HOSTNAME

ServerAPISettings

Settings for controlling API server behavior

auth_string

A string to use for basic authentication with the API in the form 'user:password'.

Type: string | None

Default: None

TOML dotted key path: server.api.auth_string

Supported environment variables: PREFECT_SERVER_API_AUTH_STRING

host

The API's host address (defaults to 127.0.0.1).

Type: string

Default: 127.0.0.1

TOML dotted key path: server.api.host

Supported environment variables: PREFECT_SERVER_API_HOST

port

The API's port address (defaults to 4200).

Type: integer

Default: 4200

TOML dotted key path: server.api.port

Supported environment variables: PREFECT_SERVER_API_PORT

base_path

The base URL path to serve the API under.

Type: string | None

Default: None

Examples:

  • "/v2/api"

TOML dotted key path: server.api.base_path

Supported environment variables: PREFECT_SERVER_API_BASE_PATH

default_limit

The default limit applied to queries that can return multiple objects, such as POST /flow_runs/filter.

Type: integer

Default: 200

TOML dotted key path: server.api.default_limit

Supported environment variables: PREFECT_SERVER_API_DEFAULT_LIMIT, PREFECT_API_DEFAULT_LIMIT

keepalive_timeout

    The API's keep alive timeout (defaults to `5`).
    Refer to https://www.uvicorn.org/settings/#timeouts for details.

    When the API is hosted behind a load balancer, you may want to set this to a value
    greater than the load balancer's idle timeout.

    Note this setting only applies when calling `prefect server start`; if hosting the
    API with another tool you will need to configure this there instead.

Type: integer

Default: 5

TOML dotted key path: server.api.keepalive_timeout

Supported environment variables: PREFECT_SERVER_API_KEEPALIVE_TIMEOUT

csrf_protection_enabled

    Controls the activation of CSRF protection for the Prefect server API.

    When enabled (`True`), the server enforces CSRF validation checks on incoming
    state-changing requests (POST, PUT, PATCH, DELETE), requiring a valid CSRF
    token to be included in the request headers or body. This adds a layer of
    security by preventing unauthorized or malicious sites from making requests on
    behalf of authenticated users.

    It is recommended to enable this setting in production environments where the
    API is exposed to web clients to safeguard against CSRF attacks.

    Note: Enabling this setting requires corresponding support in the client for
    CSRF token management. See PREFECT_CLIENT_CSRF_SUPPORT_ENABLED for more.

Type: boolean

Default: False

TOML dotted key path: server.api.csrf_protection_enabled

Supported environment variables: PREFECT_SERVER_API_CSRF_PROTECTION_ENABLED, PREFECT_SERVER_CSRF_PROTECTION_ENABLED

csrf_token_expiration

    Specifies the duration for which a CSRF token remains valid after being issued
    by the server.

    The default expiration time is set to 1 hour, which offers a reasonable
    compromise. Adjust this setting based on your specific security requirements
    and usage patterns.

Type: string

Default: PT1H

TOML dotted key path: server.api.csrf_token_expiration

Supported environment variables: PREFECT_SERVER_API_CSRF_TOKEN_EXPIRATION, PREFECT_SERVER_CSRF_TOKEN_EXPIRATION

cors_allowed_origins

    A comma-separated list of origins that are authorized to make cross-origin requests to the API.

    By default, this is set to `*`, which allows requests from all origins.

Type: string

Default: *

TOML dotted key path: server.api.cors_allowed_origins

Supported environment variables: PREFECT_SERVER_API_CORS_ALLOWED_ORIGINS, PREFECT_SERVER_CORS_ALLOWED_ORIGINS

cors_allowed_methods

    A comma-separated list of methods that are authorized to make cross-origin requests to the API.

    By default, this is set to `*`, which allows requests from all methods.

Type: string

Default: *

TOML dotted key path: server.api.cors_allowed_methods

Supported environment variables: PREFECT_SERVER_API_CORS_ALLOWED_METHODS, PREFECT_SERVER_CORS_ALLOWED_METHODS

cors_allowed_headers

    A comma-separated list of headers that are authorized to make cross-origin requests to the API.

    By default, this is set to `*`, which allows requests from all headers.

Type: string

Default: *

TOML dotted key path: server.api.cors_allowed_headers

Supported environment variables: PREFECT_SERVER_API_CORS_ALLOWED_HEADERS, PREFECT_SERVER_CORS_ALLOWED_HEADERS

max_parameter_size

The maximum size of parameters (in bytes, JSON-serialized) that can be stored on a flow run or deployment. Set to 0 to disable the limit.

Type: integer

Default: 524288

Constraints:

  • Minimum: 0

TOML dotted key path: server.api.max_parameter_size

Supported environment variables: PREFECT_SERVER_API_MAX_PARAMETER_SIZE

ServerConcurrencySettings

lease_storage

The module to use for storing concurrency limit leases.

Type: string

Default: prefect.server.concurrency.lease_storage.memory

TOML dotted key path: server.concurrency.lease_storage

Supported environment variables: PREFECT_SERVER_CONCURRENCY_LEASE_STORAGE

initial_deployment_lease_duration

Initial duration for deployment concurrency lease in seconds.

Type: number

Default: 300.0

Constraints:

  • Minimum: 30.0
  • Maximum: 3600.0

TOML dotted key path: server.concurrency.initial_deployment_lease_duration

Supported environment variables: PREFECT_SERVER_CONCURRENCY_INITIAL_DEPLOYMENT_LEASE_DURATION

maximum_concurrency_slot_wait_seconds

The maximum number of seconds to wait before retrying when a concurrency slot cannot be acquired.

Type: number

Default: 30

Constraints:

  • Minimum: 0

TOML dotted key path: server.concurrency.maximum_concurrency_slot_wait_seconds

Supported environment variables: PREFECT_SERVER_CONCURRENCY_MAXIMUM_CONCURRENCY_SLOT_WAIT_SECONDS

ServerDatabaseSettings

Settings for controlling server database behavior

sqlalchemy

Settings for controlling SQLAlchemy behavior

Type: SQLAlchemySettings

TOML dotted key path: server.database.sqlalchemy

connection_url

    A database connection URL in a SQLAlchemy-compatible
    format. Prefect currently supports SQLite and Postgres. Note that all
    Prefect database engines must use an async driver - for SQLite, use
    `sqlite+aiosqlite` and for Postgres use `postgresql+asyncpg`.

    SQLite in-memory databases can be used by providing the url
    `sqlite+aiosqlite:///file::memory:?cache=shared&uri=true&check_same_thread=false`,
    which will allow the database to be accessed by multiple threads. Note
    that in-memory databases can not be accessed from multiple processes and
    should only be used for simple tests.

Type: string | None

Default: None

TOML dotted key path: server.database.connection_url

Supported environment variables: PREFECT_SERVER_DATABASE_CONNECTION_URL, PREFECT_API_DATABASE_CONNECTION_URL

driver

The database driver to use when connecting to the database. If not set, the driver will be inferred from the connection URL.

Type: string | None

Default: None

TOML dotted key path: server.database.driver

Supported environment variables: PREFECT_SERVER_DATABASE_DRIVER, PREFECT_API_DATABASE_DRIVER

host

The database server host.

Type: string | None

Default: None

TOML dotted key path: server.database.host

Supported environment variables: PREFECT_SERVER_DATABASE_HOST, PREFECT_API_DATABASE_HOST

port

The database server port.

Type: integer | None

Default: None

TOML dotted key path: server.database.port

Supported environment variables: PREFECT_SERVER_DATABASE_PORT, PREFECT_API_DATABASE_PORT

user

The user to use when connecting to the database.

Type: string | None

Default: None

TOML dotted key path: server.database.user

Supported environment variables: PREFECT_SERVER_DATABASE_USER, PREFECT_API_DATABASE_USER

name

The name of the Prefect database on the remote server, or the path to the database file for SQLite.

Type: string | None

Default: None

TOML dotted key path: server.database.name

Supported environment variables: PREFECT_SERVER_DATABASE_NAME, PREFECT_API_DATABASE_NAME

password

The password to use when connecting to the database. Should be kept secret.

Type: string | None

Default: None

TOML dotted key path: server.database.password

Supported environment variables: PREFECT_SERVER_DATABASE_PASSWORD, PREFECT_API_DATABASE_PASSWORD

echo

If True, SQLAlchemy will log all SQL issued to the database. Defaults to False.

Type: boolean

Default: False

TOML dotted key path: server.database.echo

Supported environment variables: PREFECT_SERVER_DATABASE_ECHO, PREFECT_API_DATABASE_ECHO

migrate_on_start

If True, the database will be migrated on application startup.

Type: boolean

Default: True

TOML dotted key path: server.database.migrate_on_start

Supported environment variables: PREFECT_SERVER_DATABASE_MIGRATE_ON_START, PREFECT_API_DATABASE_MIGRATE_ON_START

timeout

A statement timeout, in seconds, applied to all database interactions made by the Prefect backend. Defaults to 10 seconds.

Type: number | None

Default: 10.0

TOML dotted key path: server.database.timeout

Supported environment variables: PREFECT_SERVER_DATABASE_TIMEOUT, PREFECT_API_DATABASE_TIMEOUT

connection_timeout

A connection timeout, in seconds, applied to database connections. Defaults to 5.

Type: number | None

Default: 5.0

TOML dotted key path: server.database.connection_timeout

Supported environment variables: PREFECT_SERVER_DATABASE_CONNECTION_TIMEOUT, PREFECT_API_DATABASE_CONNECTION_TIMEOUT

ServerDeploymentsSettings

concurrency_slot_wait_seconds

The number of seconds to wait before retrying when a deployment flow run cannot secure a concurrency slot from the server.

Type: number

Default: 30.0

Constraints:

  • Minimum: 0.0

TOML dotted key path: server.deployments.concurrency_slot_wait_seconds

Supported environment variables: PREFECT_SERVER_DEPLOYMENTS_CONCURRENCY_SLOT_WAIT_SECONDS, PREFECT_DEPLOYMENT_CONCURRENCY_SLOT_WAIT_SECONDS

ServerDocketSettings

Settings for controlling Docket behavior

name

The name of the Docket instance.

Type: string

Default: prefect-server

TOML dotted key path: server.docket.name

Supported environment variables: PREFECT_SERVER_DOCKET_NAME

url

The URL of the Redis server to use for Docket.

Type: string

Default: memory://

TOML dotted key path: server.docket.url

Supported environment variables: PREFECT_SERVER_DOCKET_URL

ServerEphemeralSettings

Settings for controlling ephemeral server behavior

enabled

    Controls whether or not a subprocess server can be started when no API URL is provided.

Type: boolean

Default: False

TOML dotted key path: server.ephemeral.enabled

Supported environment variables: PREFECT_SERVER_EPHEMERAL_ENABLED, PREFECT_SERVER_ALLOW_EPHEMERAL_MODE

startup_timeout_seconds

    The number of seconds to wait for the server to start when ephemeral mode is enabled.
    Defaults to `20`.

Type: integer

Default: 20

TOML dotted key path: server.ephemeral.startup_timeout_seconds

Supported environment variables: PREFECT_SERVER_EPHEMERAL_STARTUP_TIMEOUT_SECONDS

ServerEventsSettings

Settings for controlling behavior of the events subsystem

stream_out_enabled

Whether or not to stream events out to the API via websockets.

Type: boolean

Default: True

TOML dotted key path: server.events.stream_out_enabled

Supported environment variables: PREFECT_SERVER_EVENTS_STREAM_OUT_ENABLED, PREFECT_API_EVENTS_STREAM_OUT_ENABLED

The number of seconds to cache related resources for in the API.

Type: string

Default: PT5M

TOML dotted key path: server.events.related_resource_cache_ttl

Supported environment variables: PREFECT_SERVER_EVENTS_RELATED_RESOURCE_CACHE_TTL, PREFECT_API_EVENTS_RELATED_RESOURCE_CACHE_TTL

maximum_labels_per_resource

The maximum number of labels a resource may have.

Type: integer

Default: 500

TOML dotted key path: server.events.maximum_labels_per_resource

Supported environment variables: PREFECT_SERVER_EVENTS_MAXIMUM_LABELS_PER_RESOURCE, PREFECT_EVENTS_MAXIMUM_LABELS_PER_RESOURCE

The maximum number of related resources an Event may have.

Type: integer

Default: 100

TOML dotted key path: server.events.maximum_related_resources

Supported environment variables: PREFECT_SERVER_EVENTS_MAXIMUM_RELATED_RESOURCES, PREFECT_EVENTS_MAXIMUM_RELATED_RESOURCES

maximum_size_bytes

The maximum size of an Event when serialized to JSON

Type: integer

Default: 1500000

TOML dotted key path: server.events.maximum_size_bytes

Supported environment variables: PREFECT_SERVER_EVENTS_MAXIMUM_SIZE_BYTES, PREFECT_EVENTS_MAXIMUM_SIZE_BYTES

expired_bucket_buffer

The amount of time to retain expired automation buckets

Type: string

Default: PT1M

TOML dotted key path: server.events.expired_bucket_buffer

Supported environment variables: PREFECT_SERVER_EVENTS_EXPIRED_BUCKET_BUFFER, PREFECT_EVENTS_EXPIRED_BUCKET_BUFFER

proactive_granularity

How frequently proactive automations are evaluated

Type: string

Default: PT5S

TOML dotted key path: server.events.proactive_granularity

Supported environment variables: PREFECT_SERVER_EVENTS_PROACTIVE_GRANULARITY, PREFECT_EVENTS_PROACTIVE_GRANULARITY

retention_period

The amount of time to retain events in the database.

Type: string

Default: P7D

TOML dotted key path: server.events.retention_period

Supported environment variables: PREFECT_SERVER_EVENTS_RETENTION_PERIOD, PREFECT_EVENTS_RETENTION_PERIOD

maximum_websocket_backfill

The maximum range to look back for backfilling events for a websocket subscriber.

Type: string

Default: PT15M

TOML dotted key path: server.events.maximum_websocket_backfill

Supported environment variables: PREFECT_SERVER_EVENTS_MAXIMUM_WEBSOCKET_BACKFILL, PREFECT_EVENTS_MAXIMUM_WEBSOCKET_BACKFILL

websocket_backfill_page_size

The page size for the queries to backfill events for websocket subscribers.

Type: integer

Default: 250

TOML dotted key path: server.events.websocket_backfill_page_size

Supported environment variables: PREFECT_SERVER_EVENTS_WEBSOCKET_BACKFILL_PAGE_SIZE, PREFECT_EVENTS_WEBSOCKET_BACKFILL_PAGE_SIZE

messaging_broker

Which message broker implementation to use for the messaging system, should point to a module that exports a Publisher and Consumer class.

Type: string

Default: prefect.server.utilities.messaging.memory

TOML dotted key path: server.events.messaging_broker

Supported environment variables: PREFECT_SERVER_EVENTS_MESSAGING_BROKER, PREFECT_MESSAGING_BROKER

messaging_cache

Which cache implementation to use for the events system. Should point to a module that exports a Cache class.

Type: string

Default: prefect.server.utilities.messaging.memory

TOML dotted key path: server.events.messaging_cache

Supported environment variables: PREFECT_SERVER_EVENTS_MESSAGING_CACHE, PREFECT_MESSAGING_CACHE

causal_ordering

Which causal ordering implementation to use for the events system. Should point to a module that exports a CausalOrdering class.

Type: string

Default: prefect.server.events.ordering.memory

TOML dotted key path: server.events.causal_ordering

Supported environment variables: PREFECT_SERVER_EVENTS_CAUSAL_ORDERING

maximum_event_name_length

The maximum length of an event name.

Type: integer

Default: 1024

TOML dotted key path: server.events.maximum_event_name_length

Supported environment variables: PREFECT_SERVER_EVENTS_MAXIMUM_EVENT_NAME_LENGTH

ServerFlowRunGraphSettings

Settings for controlling behavior of the flow run graph

max_nodes

The maximum size of a flow run graph on the v2 API

Type: integer

Default: 10000

TOML dotted key path: server.flow_run_graph.max_nodes

Supported environment variables: PREFECT_SERVER_FLOW_RUN_GRAPH_MAX_NODES, PREFECT_API_MAX_FLOW_RUN_GRAPH_NODES

max_artifacts

The maximum number of artifacts to show on a flow run graph on the v2 API

Type: integer

Default: 10000

TOML dotted key path: server.flow_run_graph.max_artifacts

Supported environment variables: PREFECT_SERVER_FLOW_RUN_GRAPH_MAX_ARTIFACTS, PREFECT_API_MAX_FLOW_RUN_GRAPH_ARTIFACTS

ServerLogsSettings

Settings for controlling behavior of the logs subsystem

stream_out_enabled

Whether or not to stream logs out to the API via websockets.

Type: boolean

Default: False

TOML dotted key path: server.logs.stream_out_enabled

Supported environment variables: PREFECT_SERVER_LOGS_STREAM_OUT_ENABLED

stream_publishing_enabled

Whether or not to publish logs to the streaming system.

Type: boolean

Default: False

TOML dotted key path: server.logs.stream_publishing_enabled

Supported environment variables: PREFECT_SERVER_LOGS_STREAM_PUBLISHING_ENABLED

ServerServicesCancellationCleanupSettings

Settings for controlling the cancellation cleanup service

enabled

Whether or not to start the cancellation cleanup service in the server application.

Type: boolean

Default: True

TOML dotted key path: server.services.cancellation_cleanup.enabled

Supported environment variables: PREFECT_SERVER_SERVICES_CANCELLATION_CLEANUP_ENABLED, PREFECT_API_SERVICES_CANCELLATION_CLEANUP_ENABLED

loop_seconds

The cancellation cleanup service will look for non-terminal tasks and subflows this often. Defaults to 20.

Type: number

Default: 20

TOML dotted key path: server.services.cancellation_cleanup.loop_seconds

Supported environment variables: PREFECT_SERVER_SERVICES_CANCELLATION_CLEANUP_LOOP_SECONDS, PREFECT_API_SERVICES_CANCELLATION_CLEANUP_LOOP_SECONDS

ServerServicesDBVacuumSettings

Settings for controlling the database vacuum service

enabled

Comma-separated set of vacuum types to enable. Valid values: 'events', 'flow_runs'. Defaults to 'events'. For backward compatibility, 'true' maps to 'events,flow_runs' and 'false' maps to 'events'. Event vacuum also requires event_persister.enabled (the default).

Type: array | boolean | None

Default: ['events']

TOML dotted key path: server.services.db_vacuum.enabled

Supported environment variables: PREFECT_SERVER_SERVICES_DB_VACUUM_ENABLED

loop_seconds

The database vacuum service will run this often, in seconds. Defaults to 3600 (1 hour).

Type: number

Default: 3600

TOML dotted key path: server.services.db_vacuum.loop_seconds

Supported environment variables: PREFECT_SERVER_SERVICES_DB_VACUUM_LOOP_SECONDS

retention_period

How old a flow run must be (based on end_time) before it is eligible for deletion. Accepts seconds. Minimum 1 hour. Defaults to 90 days.

Type: string

Default: P90D

TOML dotted key path: server.services.db_vacuum.retention_period

Supported environment variables: PREFECT_SERVER_SERVICES_DB_VACUUM_RETENTION_PERIOD

batch_size

The number of records to delete per database transaction. Defaults to 200.

Type: integer

Default: 200

TOML dotted key path: server.services.db_vacuum.batch_size

Supported environment variables: PREFECT_SERVER_SERVICES_DB_VACUUM_BATCH_SIZE

event_retention_overrides

Per-event-type retention period overrides. Keys are event type strings (e.g. 'prefect.flow-run.heartbeat'), values are retention periods in seconds. Event types not listed fall back to server.events.retention_period. Each override is capped by the global events retention period.

Type: object

Default: {'prefect.flow-run.heartbeat': 'P7D'}

TOML dotted key path: server.services.db_vacuum.event_retention_overrides

Supported environment variables: PREFECT_SERVER_SERVICES_DB_VACUUM_EVENT_RETENTION_OVERRIDES

ServerServicesEventLoggerSettings

Settings for controlling the event logger service

enabled

Whether or not to start the event logger service in the server application.

Type: boolean

Default: False

TOML dotted key path: server.services.event_logger.enabled

Supported environment variables: PREFECT_SERVER_SERVICES_EVENT_LOGGER_ENABLED, PREFECT_API_SERVICES_EVENT_LOGGER_ENABLED

ServerServicesEventPersisterSettings

Settings for controlling the event persister service

enabled

Whether or not to start the event persister service in the server application.

Type: boolean

Default: True

TOML dotted key path: server.services.event_persister.enabled

Supported environment variables: PREFECT_SERVER_SERVICES_EVENT_PERSISTER_ENABLED, PREFECT_API_SERVICES_EVENT_PERSISTER_ENABLED

batch_size

The number of events the event persister will attempt to insert in one batch.

Type: integer

Default: 20

TOML dotted key path: server.services.event_persister.batch_size

Supported environment variables: PREFECT_SERVER_SERVICES_EVENT_PERSISTER_BATCH_SIZE, PREFECT_API_SERVICES_EVENT_PERSISTER_BATCH_SIZE

read_batch_size

The number of events the event persister will attempt to read from the message broker in one batch.

Type: integer

Default: 1

TOML dotted key path: server.services.event_persister.read_batch_size

Supported environment variables: PREFECT_SERVER_SERVICES_EVENT_PERSISTER_READ_BATCH_SIZE, PREFECT_API_SERVICES_EVENT_PERSISTER_READ_BATCH_SIZE

flush_interval

The maximum number of seconds between flushes of the event persister.

Type: number

Default: 5

TOML dotted key path: server.services.event_persister.flush_interval

Supported environment variables: PREFECT_SERVER_SERVICES_EVENT_PERSISTER_FLUSH_INTERVAL, PREFECT_API_SERVICES_EVENT_PERSISTER_FLUSH_INTERVAL

queue_max_size

The maximum number of events that can be queued in memory for persistence. When the queue is full, new events will be dropped.

Type: integer

Default: 50000

TOML dotted key path: server.services.event_persister.queue_max_size

Supported environment variables: PREFECT_SERVER_SERVICES_EVENT_PERSISTER_QUEUE_MAX_SIZE

max_flush_retries

The maximum number of consecutive flush failures before events are dropped instead of being re-queued.

Type: integer

Default: 5

TOML dotted key path: server.services.event_persister.max_flush_retries

Supported environment variables: PREFECT_SERVER_SERVICES_EVENT_PERSISTER_MAX_FLUSH_RETRIES

ServerServicesForemanSettings

Settings for controlling the foreman service

enabled

Whether or not to start the foreman service in the server application.

Type: boolean

Default: True

TOML dotted key path: server.services.foreman.enabled

Supported environment variables: PREFECT_SERVER_SERVICES_FOREMAN_ENABLED, PREFECT_API_SERVICES_FOREMAN_ENABLED

loop_seconds

The foreman service will check for offline workers this often. Defaults to 15.

Type: number

Default: 15

TOML dotted key path: server.services.foreman.loop_seconds

Supported environment variables: PREFECT_SERVER_SERVICES_FOREMAN_LOOP_SECONDS, PREFECT_API_SERVICES_FOREMAN_LOOP_SECONDS

inactivity_heartbeat_multiple

    The number of heartbeats that must be missed before a worker is marked as offline. Defaults to `3`.

Type: integer

Default: 3

TOML dotted key path: server.services.foreman.inactivity_heartbeat_multiple

Supported environment variables: PREFECT_SERVER_SERVICES_FOREMAN_INACTIVITY_HEARTBEAT_MULTIPLE, PREFECT_API_SERVICES_FOREMAN_INACTIVITY_HEARTBEAT_MULTIPLE

fallback_heartbeat_interval_seconds

    The number of seconds to use for online/offline evaluation if a worker's heartbeat
    interval is not set. Defaults to `30`.

Type: integer

Default: 30

TOML dotted key path: server.services.foreman.fallback_heartbeat_interval_seconds

Supported environment variables: PREFECT_SERVER_SERVICES_FOREMAN_FALLBACK_HEARTBEAT_INTERVAL_SECONDS, PREFECT_API_SERVICES_FOREMAN_FALLBACK_HEARTBEAT_INTERVAL_SECONDS

deployment_last_polled_timeout_seconds

    The number of seconds before a deployment is marked as not ready if it has not been
    polled. Defaults to `60`.

Type: integer

Default: 60

TOML dotted key path: server.services.foreman.deployment_last_polled_timeout_seconds

Supported environment variables: PREFECT_SERVER_SERVICES_FOREMAN_DEPLOYMENT_LAST_POLLED_TIMEOUT_SECONDS, PREFECT_API_SERVICES_FOREMAN_DEPLOYMENT_LAST_POLLED_TIMEOUT_SECONDS

work_queue_last_polled_timeout_seconds

    The number of seconds before a work queue is marked as not ready if it has not been
    polled. Defaults to `60`.

Type: integer

Default: 60

TOML dotted key path: server.services.foreman.work_queue_last_polled_timeout_seconds

Supported environment variables: PREFECT_SERVER_SERVICES_FOREMAN_WORK_QUEUE_LAST_POLLED_TIMEOUT_SECONDS, PREFECT_API_SERVICES_FOREMAN_WORK_QUEUE_LAST_POLLED_TIMEOUT_SECONDS

ServerServicesLateRunsSettings

Settings for controlling the late runs service

enabled

Whether or not to start the late runs service in the server application.

Type: boolean

Default: True

TOML dotted key path: server.services.late_runs.enabled

Supported environment variables: PREFECT_SERVER_SERVICES_LATE_RUNS_ENABLED, PREFECT_API_SERVICES_LATE_RUNS_ENABLED

loop_seconds

    The late runs service will look for runs to mark as late this often. Defaults to `5`.

Type: number

Default: 5

TOML dotted key path: server.services.late_runs.loop_seconds

Supported environment variables: PREFECT_SERVER_SERVICES_LATE_RUNS_LOOP_SECONDS, PREFECT_API_SERVICES_LATE_RUNS_LOOP_SECONDS

after_seconds

    The late runs service will mark runs as late after they have exceeded their scheduled start time by this many seconds. Defaults to `5` seconds.

Type: string

Default: PT15S

TOML dotted key path: server.services.late_runs.after_seconds

Supported environment variables: PREFECT_SERVER_SERVICES_LATE_RUNS_AFTER_SECONDS, PREFECT_API_SERVICES_LATE_RUNS_AFTER_SECONDS

ServerServicesPauseExpirationsSettings

Settings for controlling the pause expiration service

enabled

    Whether or not to start the paused flow run expiration service in the server
    application. If disabled, paused flows that have timed out will remain in a Paused state
    until a resume attempt.

Type: boolean

Default: True

TOML dotted key path: server.services.pause_expirations.enabled

Supported environment variables: PREFECT_SERVER_SERVICES_PAUSE_EXPIRATIONS_ENABLED, PREFECT_API_SERVICES_PAUSE_EXPIRATIONS_ENABLED

loop_seconds

    The pause expiration service will look for runs to mark as failed this often. Defaults to `5`.

Type: number

Default: 5

TOML dotted key path: server.services.pause_expirations.loop_seconds

Supported environment variables: PREFECT_SERVER_SERVICES_PAUSE_EXPIRATIONS_LOOP_SECONDS, PREFECT_API_SERVICES_PAUSE_EXPIRATIONS_LOOP_SECONDS

ServerServicesRepossessorSettings

Settings for controlling the repossessor service

enabled

Whether or not to start the repossessor service in the server application.

Type: boolean

Default: True

TOML dotted key path: server.services.repossessor.enabled

Supported environment variables: PREFECT_SERVER_SERVICES_REPOSSESSOR_ENABLED

loop_seconds

The repossessor service will look for expired leases this often. Defaults to 15.

Type: number

Default: 15

TOML dotted key path: server.services.repossessor.loop_seconds

Supported environment variables: PREFECT_SERVER_SERVICES_REPOSSESSOR_LOOP_SECONDS

ServerServicesSchedulerSettings

Settings for controlling the scheduler service

enabled

Whether or not to start the scheduler service in the server application.

Type: boolean

Default: True

TOML dotted key path: server.services.scheduler.enabled

Supported environment variables: PREFECT_SERVER_SERVICES_SCHEDULER_ENABLED, PREFECT_API_SERVICES_SCHEDULER_ENABLED

loop_seconds

    The scheduler loop interval, in seconds. This determines
    how often the scheduler will attempt to schedule new flow runs, but has no
    impact on how quickly either flow runs or task runs are actually executed.
    Defaults to `60`.

Type: number

Default: 60

TOML dotted key path: server.services.scheduler.loop_seconds

Supported environment variables: PREFECT_SERVER_SERVICES_SCHEDULER_LOOP_SECONDS, PREFECT_API_SERVICES_SCHEDULER_LOOP_SECONDS

deployment_batch_size

    The number of deployments the scheduler will attempt to
    schedule in a single batch. If there are more deployments than the batch
    size, the scheduler immediately attempts to schedule the next batch; it
    does not sleep for `scheduler_loop_seconds` until it has visited every
    deployment once. Defaults to `100`.

Type: integer

Default: 100

TOML dotted key path: server.services.scheduler.deployment_batch_size

Supported environment variables: PREFECT_SERVER_SERVICES_SCHEDULER_DEPLOYMENT_BATCH_SIZE, PREFECT_API_SERVICES_SCHEDULER_DEPLOYMENT_BATCH_SIZE

max_runs

    The scheduler will attempt to schedule up to this many
    auto-scheduled runs in the future. Note that runs may have fewer than
    this many scheduled runs, depending on the value of
    `scheduler_max_scheduled_time`.  Defaults to `100`.

Type: integer

Default: 100

TOML dotted key path: server.services.scheduler.max_runs

Supported environment variables: PREFECT_SERVER_SERVICES_SCHEDULER_MAX_RUNS, PREFECT_API_SERVICES_SCHEDULER_MAX_RUNS

min_runs

    The scheduler will attempt to schedule at least this many
    auto-scheduled runs in the future. Note that runs may have more than
    this many scheduled runs, depending on the value of
    `scheduler_min_scheduled_time`.  Defaults to `3`.

Type: integer

Default: 3

TOML dotted key path: server.services.scheduler.min_runs

Supported environment variables: PREFECT_SERVER_SERVICES_SCHEDULER_MIN_RUNS, PREFECT_API_SERVICES_SCHEDULER_MIN_RUNS

max_scheduled_time

    The scheduler will create new runs up to this far in the
    future. Note that this setting will take precedence over
    `scheduler_max_runs`: if a flow runs once a month and
    `scheduler_max_scheduled_time` is three months, then only three runs will be
    scheduled. Defaults to 100 days (`8640000` seconds).

Type: string

Default: P100D

TOML dotted key path: server.services.scheduler.max_scheduled_time

Supported environment variables: PREFECT_SERVER_SERVICES_SCHEDULER_MAX_SCHEDULED_TIME, PREFECT_API_SERVICES_SCHEDULER_MAX_SCHEDULED_TIME

min_scheduled_time

    The scheduler will create new runs at least this far in the
    future. Note that this setting will take precedence over `scheduler_min_runs`:
    if a flow runs every hour and `scheduler_min_scheduled_time` is three hours,
    then three runs will be scheduled even if `scheduler_min_runs` is 1. Defaults to

Type: string

Default: PT1H

TOML dotted key path: server.services.scheduler.min_scheduled_time

Supported environment variables: PREFECT_SERVER_SERVICES_SCHEDULER_MIN_SCHEDULED_TIME, PREFECT_API_SERVICES_SCHEDULER_MIN_SCHEDULED_TIME

insert_batch_size

    The number of runs the scheduler will attempt to insert in a single batch.
    Defaults to `500`.

Type: integer

Default: 500

TOML dotted key path: server.services.scheduler.insert_batch_size

Supported environment variables: PREFECT_SERVER_SERVICES_SCHEDULER_INSERT_BATCH_SIZE, PREFECT_API_SERVICES_SCHEDULER_INSERT_BATCH_SIZE

recent_deployments_loop_seconds

    The number of seconds the recent deployments scheduler will wait between checking for recently updated deployments. Defaults to `5`.

Type: number

Default: 5

TOML dotted key path: server.services.scheduler.recent_deployments_loop_seconds

Supported environment variables: PREFECT_SERVER_SERVICES_SCHEDULER_RECENT_DEPLOYMENTS_LOOP_SECONDS

ServerServicesSettings

Settings for controlling server services

cancellation_cleanup

Type: ServerServicesCancellationCleanupSettings

TOML dotted key path: server.services.cancellation_cleanup

db_vacuum

Type: ServerServicesDBVacuumSettings

TOML dotted key path: server.services.db_vacuum

event_persister

Type: ServerServicesEventPersisterSettings

TOML dotted key path: server.services.event_persister

event_logger

Type: ServerServicesEventLoggerSettings

TOML dotted key path: server.services.event_logger

foreman

Type: ServerServicesForemanSettings

TOML dotted key path: server.services.foreman

late_runs

Type: ServerServicesLateRunsSettings

TOML dotted key path: server.services.late_runs

scheduler

Type: ServerServicesSchedulerSettings

TOML dotted key path: server.services.scheduler

pause_expirations

Type: ServerServicesPauseExpirationsSettings

TOML dotted key path: server.services.pause_expirations

repossessor

Type: ServerServicesRepossessorSettings

TOML dotted key path: server.services.repossessor

task_run_recorder

Type: ServerServicesTaskRunRecorderSettings

TOML dotted key path: server.services.task_run_recorder

triggers

Type: ServerServicesTriggersSettings

TOML dotted key path: server.services.triggers

ServerServicesTaskRunRecorderSettings

Settings for controlling the task run recorder service

enabled

Whether or not to start the task run recorder service in the server application.

Type: boolean

Default: True

TOML dotted key path: server.services.task_run_recorder.enabled

Supported environment variables: PREFECT_SERVER_SERVICES_TASK_RUN_RECORDER_ENABLED, PREFECT_API_SERVICES_TASK_RUN_RECORDER_ENABLED

read_batch_size

The number of task runs the task run recorder will attempt to read from the message broker in one batch.

Type: integer

Default: 1

TOML dotted key path: server.services.task_run_recorder.read_batch_size

Supported environment variables: PREFECT_SERVER_SERVICES_TASK_RUN_RECORDER_READ_BATCH_SIZE

batch_size

The number of task runs the task run recorder will attempt to insert in one batch.

Type: integer

Default: 1

TOML dotted key path: server.services.task_run_recorder.batch_size

Supported environment variables: PREFECT_SERVER_SERVICES_TASK_RUN_RECORDER_BATCH_SIZE

flush_interval

The maximum number of seconds between flushes of the task run recorder.

Type: number

Default: 5

TOML dotted key path: server.services.task_run_recorder.flush_interval

Supported environment variables: PREFECT_SERVER_SERVICES_TASK_RUN_RECORDER_FLUSH_INTERVAL

ServerServicesTriggersSettings

Settings for controlling the triggers service

enabled

Whether or not to start the triggers service in the server application.

Type: boolean

Default: True

TOML dotted key path: server.services.triggers.enabled

Supported environment variables: PREFECT_SERVER_SERVICES_TRIGGERS_ENABLED, PREFECT_API_SERVICES_TRIGGERS_ENABLED

read_batch_size

The number of events the triggers service will attempt to read from the message broker in one batch.

Type: integer

Default: 1

TOML dotted key path: server.services.triggers.read_batch_size

Supported environment variables: PREFECT_SERVER_SERVICES_TRIGGERS_READ_BATCH_SIZE

pg_notify_reconnect_interval_seconds

    The number of seconds to wait before reconnecting to the PostgreSQL NOTIFY/LISTEN 
    connection after an error. Only used when using PostgreSQL as the database.
    Defaults to `10`.

Type: integer

Default: 10

TOML dotted key path: server.services.triggers.pg_notify_reconnect_interval_seconds

Supported environment variables: PREFECT_SERVER_SERVICES_TRIGGERS_PG_NOTIFY_RECONNECT_INTERVAL_SECONDS

pg_notify_heartbeat_interval_seconds

    The number of seconds between heartbeat checks for the PostgreSQL NOTIFY/LISTEN 
    connection to ensure it's still alive. Only used when using PostgreSQL as the database.
    Defaults to `5`.

Type: integer

Default: 5

TOML dotted key path: server.services.triggers.pg_notify_heartbeat_interval_seconds

Supported environment variables: PREFECT_SERVER_SERVICES_TRIGGERS_PG_NOTIFY_HEARTBEAT_INTERVAL_SECONDS

ServerSettings

Settings for controlling server behavior

logging_level

The default logging level for the Prefect API server.

Type: string

Default: WARNING

Constraints:

  • Allowed values: 'DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'

TOML dotted key path: server.logging_level

Supported environment variables: PREFECT_SERVER_LOGGING_LEVEL, PREFECT_LOGGING_SERVER_LEVEL

analytics_enabled

    When enabled, Prefect sends anonymous data (e.g. count of flow runs, package version)
    on server startup to help us improve our product.

Type: boolean

Default: True

TOML dotted key path: server.analytics_enabled

Supported environment variables: PREFECT_SERVER_ANALYTICS_ENABLED

metrics_enabled

Whether or not to enable Prometheus metrics in the API.

Type: boolean

Default: False

TOML dotted key path: server.metrics_enabled

Supported environment variables: PREFECT_SERVER_METRICS_ENABLED, PREFECT_API_ENABLE_METRICS

log_retryable_errors

If True, log retryable errors in the API and it's services.

Type: boolean

Default: False

TOML dotted key path: server.log_retryable_errors

Supported environment variables: PREFECT_SERVER_LOG_RETRYABLE_ERRORS, PREFECT_API_LOG_RETRYABLE_ERRORS

register_blocks_on_start

If set, any block types that have been imported will be registered with the backend on application startup. If not set, block types must be manually registered.

Type: boolean

Default: True

TOML dotted key path: server.register_blocks_on_start

Supported environment variables: PREFECT_SERVER_REGISTER_BLOCKS_ON_START, PREFECT_API_BLOCKS_REGISTER_ON_START

memoize_block_auto_registration

Controls whether or not block auto-registration on start

Type: boolean

Default: True

TOML dotted key path: server.memoize_block_auto_registration

Supported environment variables: PREFECT_SERVER_MEMOIZE_BLOCK_AUTO_REGISTRATION, PREFECT_MEMOIZE_BLOCK_AUTO_REGISTRATION

memo_store_path

Path to the memo store file. Defaults to $PREFECT_HOME/memo_store.toml

Type: string

TOML dotted key path: server.memo_store_path

Supported environment variables: PREFECT_SERVER_MEMO_STORE_PATH, PREFECT_MEMO_STORE_PATH

deployment_schedule_max_scheduled_runs

The maximum number of scheduled runs to create for a deployment.

Type: integer

Default: 50

TOML dotted key path: server.deployment_schedule_max_scheduled_runs

Supported environment variables: PREFECT_SERVER_DEPLOYMENT_SCHEDULE_MAX_SCHEDULED_RUNS, PREFECT_DEPLOYMENT_SCHEDULE_MAX_SCHEDULED_RUNS

api

Type: ServerAPISettings

TOML dotted key path: server.api

concurrency

Settings for controlling server-side concurrency limit handling

Type: ServerConcurrencySettings

TOML dotted key path: server.concurrency

database

Type: ServerDatabaseSettings

TOML dotted key path: server.database

deployments

Settings for controlling server deployments behavior

Type: ServerDeploymentsSettings

TOML dotted key path: server.deployments

docket

Settings for controlling server Docket behavior

Type: ServerDocketSettings

TOML dotted key path: server.docket

ephemeral

Type: ServerEphemeralSettings

TOML dotted key path: server.ephemeral

events

Settings for controlling server events behavior

Type: ServerEventsSettings

TOML dotted key path: server.events

flow_run_graph

Settings for controlling flow run graph behavior

Type: ServerFlowRunGraphSettings

TOML dotted key path: server.flow_run_graph

logs

Settings for controlling server logs behavior

Type: ServerLogsSettings

TOML dotted key path: server.logs

services

Settings for controlling server services behavior

Type: ServerServicesSettings

TOML dotted key path: server.services

tasks

Settings for controlling server tasks behavior

Type: ServerTasksSettings

TOML dotted key path: server.tasks

ui

Settings for controlling server UI behavior

Type: ServerUISettings

TOML dotted key path: server.ui

ServerTasksSchedulingSettings

Settings for controlling server-side behavior related to task scheduling

max_scheduled_queue_size

The maximum number of scheduled tasks to queue for submission.

Type: integer

Default: 1000

TOML dotted key path: server.tasks.scheduling.max_scheduled_queue_size

Supported environment variables: PREFECT_SERVER_TASKS_SCHEDULING_MAX_SCHEDULED_QUEUE_SIZE, PREFECT_TASK_SCHEDULING_MAX_SCHEDULED_QUEUE_SIZE

max_retry_queue_size

The maximum number of retries to queue for submission.

Type: integer

Default: 100

TOML dotted key path: server.tasks.scheduling.max_retry_queue_size

Supported environment variables: PREFECT_SERVER_TASKS_SCHEDULING_MAX_RETRY_QUEUE_SIZE, PREFECT_TASK_SCHEDULING_MAX_RETRY_QUEUE_SIZE

pending_task_timeout

How long before a PENDING task are made available to another task worker.

Type: string

Default: PT0S

TOML dotted key path: server.tasks.scheduling.pending_task_timeout

Supported environment variables: PREFECT_SERVER_TASKS_SCHEDULING_PENDING_TASK_TIMEOUT, PREFECT_TASK_SCHEDULING_PENDING_TASK_TIMEOUT

ServerTasksSettings

Settings for controlling server-side behavior related to tasks

tag_concurrency_slot_wait_seconds

The number of seconds to wait before retrying when a task run cannot secure a concurrency slot from the server.

Type: number

Default: 10

Constraints:

  • Minimum: 0

TOML dotted key path: server.tasks.tag_concurrency_slot_wait_seconds

Supported environment variables: PREFECT_SERVER_TASKS_TAG_CONCURRENCY_SLOT_WAIT_SECONDS, PREFECT_TASK_RUN_TAG_CONCURRENCY_SLOT_WAIT_SECONDS

max_cache_key_length

The maximum number of characters allowed for a task run cache key.

Type: integer

Default: 2000

TOML dotted key path: server.tasks.max_cache_key_length

Supported environment variables: PREFECT_SERVER_TASKS_MAX_CACHE_KEY_LENGTH, PREFECT_API_TASK_CACHE_KEY_MAX_LENGTH

scheduling

Type: ServerTasksSchedulingSettings

TOML dotted key path: server.tasks.scheduling

ServerUISettings

enabled

Whether or not to serve the Prefect UI.

Type: boolean

Default: True

TOML dotted key path: server.ui.enabled

Supported environment variables: PREFECT_SERVER_UI_ENABLED, PREFECT_UI_ENABLED

v2_enabled

Whether neutral UI entry points should default to the experimental V2 UI instead of V1 when the browser has no saved UI preference.

Type: boolean

Default: False

TOML dotted key path: server.ui.v2_enabled

Supported environment variables: PREFECT_SERVER_UI_V2_ENABLED

api_url

The connection url for communication from the UI to the API. Defaults to PREFECT_API_URL if set. Otherwise, the default URL is generated from PREFECT_SERVER_API_HOST and PREFECT_SERVER_API_PORT.

Type: string | None

Default: None

TOML dotted key path: server.ui.api_url

Supported environment variables: PREFECT_SERVER_UI_API_URL, PREFECT_UI_API_URL

serve_base

The base URL path to serve the Prefect UI from.

Type: string

Default: /

TOML dotted key path: server.ui.serve_base

Supported environment variables: PREFECT_SERVER_UI_SERVE_BASE, PREFECT_UI_SERVE_BASE

static_directory

The directory to serve static files from. This should be used when running into permissions issues when attempting to serve the UI from the default directory (for example when running in a Docker container).

Type: string | None

Default: None

TOML dotted key path: server.ui.static_directory

Supported environment variables: PREFECT_SERVER_UI_STATIC_DIRECTORY, PREFECT_UI_STATIC_DIRECTORY

show_promotional_content

Whether or not to display promotional content in the UI, including upgrade prompts and marketing banners.

Type: boolean

Default: True

TOML dotted key path: server.ui.show_promotional_content

Supported environment variables: PREFECT_SERVER_UI_SHOW_PROMOTIONAL_CONTENT

TasksRunnerSettings

thread_pool_max_workers

The maximum number of workers for ThreadPoolTaskRunner.

Type: integer | None

Default: None

TOML dotted key path: tasks.runner.thread_pool_max_workers

Supported environment variables: PREFECT_TASKS_RUNNER_THREAD_POOL_MAX_WORKERS, PREFECT_TASK_RUNNER_THREAD_POOL_MAX_WORKERS

process_pool_max_workers

The maximum number of workers for ProcessPoolTaskRunner.

Type: integer | None

Default: None

TOML dotted key path: tasks.runner.process_pool_max_workers

Supported environment variables: PREFECT_TASKS_RUNNER_PROCESS_POOL_MAX_WORKERS

TasksSchedulingSettings

default_storage_block

The block-type/block-document slug of a block to use as the default storage for autonomous tasks.

Type: string | None

Default: None

TOML dotted key path: tasks.scheduling.default_storage_block

Supported environment variables: PREFECT_TASKS_SCHEDULING_DEFAULT_STORAGE_BLOCK, PREFECT_TASK_SCHEDULING_DEFAULT_STORAGE_BLOCK

delete_failed_submissions

Whether or not to delete failed task submissions from the database.

Type: boolean

Default: True

TOML dotted key path: tasks.scheduling.delete_failed_submissions

Supported environment variables: PREFECT_TASKS_SCHEDULING_DELETE_FAILED_SUBMISSIONS, PREFECT_TASK_SCHEDULING_DELETE_FAILED_SUBMISSIONS

TasksSettings

refresh_cache

If True, enables a refresh of cached results: re-executing the task will refresh the cached results.

Type: boolean

Default: False

TOML dotted key path: tasks.refresh_cache

Supported environment variables: PREFECT_TASKS_REFRESH_CACHE

default_no_cache

If True, sets the default cache policy on all tasks to NO_CACHE.

Type: boolean

Default: False

TOML dotted key path: tasks.default_no_cache

Supported environment variables: PREFECT_TASKS_DEFAULT_NO_CACHE

disable_caching

If True, disables caching on all tasks regardless of cache policy.

Type: boolean

Default: False

TOML dotted key path: tasks.disable_caching

Supported environment variables: PREFECT_TASKS_DISABLE_CACHING

default_retries

This value sets the default number of retries for all tasks.

Type: integer

Default: 0

Constraints:

  • Minimum: 0

TOML dotted key path: tasks.default_retries

Supported environment variables: PREFECT_TASKS_DEFAULT_RETRIES, PREFECT_TASK_DEFAULT_RETRIES

default_retry_delay_seconds

This value sets the default retry delay seconds for all tasks.

Type: string | integer | number | array | None

Default: 0

TOML dotted key path: tasks.default_retry_delay_seconds

Supported environment variables: PREFECT_TASKS_DEFAULT_RETRY_DELAY_SECONDS, PREFECT_TASK_DEFAULT_RETRY_DELAY_SECONDS

default_persist_result

If True, results will be persisted by default for all tasks. Set to False to disable persistence by default. Note that setting to False will override the behavior set by a parent flow or task.

Type: boolean | None

Default: None

TOML dotted key path: tasks.default_persist_result

Supported environment variables: PREFECT_TASKS_DEFAULT_PERSIST_RESULT

runner

Settings for controlling task runner behavior

Type: TasksRunnerSettings

TOML dotted key path: tasks.runner

scheduling

Settings for controlling client-side task scheduling behavior

Type: TasksSchedulingSettings

TOML dotted key path: tasks.scheduling

TelemetrySettings

Settings for configuring Prefect telemetry

enable_resource_metrics

Whether to enable OS-level resource metric collection in flow run subprocesses.

Type: boolean

Default: True

TOML dotted key path: telemetry.enable_resource_metrics

Supported environment variables: PREFECT_TELEMETRY_ENABLE_RESOURCE_METRICS

resource_metrics_interval_seconds

Interval in seconds between resource metric collections.

Type: integer

Default: 10

Constraints:

  • Minimum: 1

TOML dotted key path: telemetry.resource_metrics_interval_seconds

Supported environment variables: PREFECT_TELEMETRY_RESOURCE_METRICS_INTERVAL_SECONDS

TestingSettings

test_mode

If True, places the API in test mode. This may modify behavior to facilitate testing.

Type: boolean

Default: False

TOML dotted key path: testing.test_mode

Supported environment variables: PREFECT_TESTING_TEST_MODE, PREFECT_TEST_MODE

unit_test_mode

This setting only exists to facilitate unit testing. If True, code is executing in a unit test context. Defaults to False.

Type: boolean

Default: False

TOML dotted key path: testing.unit_test_mode

Supported environment variables: PREFECT_TESTING_UNIT_TEST_MODE, PREFECT_UNIT_TEST_MODE

unit_test_loop_debug

If True turns on debug mode for the unit testing event loop.

Type: boolean

Default: True

TOML dotted key path: testing.unit_test_loop_debug

Supported environment variables: PREFECT_TESTING_UNIT_TEST_LOOP_DEBUG, PREFECT_UNIT_TEST_LOOP_DEBUG

test_setting

This setting only exists to facilitate unit testing. If in test mode, this setting will return its value. Otherwise, it returns None.

Type: None

Default: FOO

TOML dotted key path: testing.test_setting

Supported environment variables: PREFECT_TESTING_TEST_SETTING, PREFECT_TEST_SETTING

WorkerSettings

debug_mode

If True, enables debug mode for the worker only. Unlike PREFECT_DEBUG_MODE, this setting does not propagate to flow runs executed by the worker.

Type: boolean

Default: False

TOML dotted key path: worker.debug_mode

Supported environment variables: PREFECT_WORKER_DEBUG_MODE

heartbeat_seconds

Number of seconds a worker should wait between sending a heartbeat.

Type: number

Default: 30

TOML dotted key path: worker.heartbeat_seconds

Supported environment variables: PREFECT_WORKER_HEARTBEAT_SECONDS

query_seconds

Number of seconds a worker should wait between queries for scheduled work.

Type: number

Default: 10

TOML dotted key path: worker.query_seconds

Supported environment variables: PREFECT_WORKER_QUERY_SECONDS

prefetch_seconds

The number of seconds into the future a worker should query for scheduled work.

Type: number

Default: 10

TOML dotted key path: worker.prefetch_seconds

Supported environment variables: PREFECT_WORKER_PREFETCH_SECONDS

enable_cancellation

Enable worker-side flow run cancellation for pending flow runs. When enabled, the worker will terminate infrastructure for flow runs that are cancelled while still in PENDING state (before the runner starts).

Type: boolean

Default: False

TOML dotted key path: worker.enable_cancellation

Supported environment variables: PREFECT_WORKER_ENABLE_CANCELLATION

cancellation_poll_seconds

Number of seconds between polls for cancelling flow runs. Used as a fallback when the WebSocket connection for real-time cancellation events is unavailable.

Type: number

Default: 120

TOML dotted key path: worker.cancellation_poll_seconds

Supported environment variables: PREFECT_WORKER_CANCELLATION_POLL_SECONDS

webserver

Settings for a worker's webserver

Type: WorkerWebserverSettings

TOML dotted key path: worker.webserver

WorkerWebserverSettings

host

The host address the worker's webserver should bind to.

Type: string

Default: 0.0.0.0

TOML dotted key path: worker.webserver.host

Supported environment variables: PREFECT_WORKER_WEBSERVER_HOST

port

The port the worker's webserver should bind to.

Type: integer

Default: 8080

TOML dotted key path: worker.webserver.port

Supported environment variables: PREFECT_WORKER_WEBSERVER_PORT