# Transport Options (/integrations/celery/reference/transport-options)
`kubemq-celery` is a [Kombu](https://docs.celeryq.dev/projects/kombu/) virtual transport for KubeMQ — it sends Celery task messages over [KubeMQ Queues](/learn/queues) and routes pidbox and monitoring traffic over [KubeMQ Events](/learn/events). Everything beyond the broker URL is tuned through two option dictionaries: `broker_transport_options` for the task transport and `result_backend_transport_options` for the queue-peek result backend. This page is the exhaustive key-by-key reference for both. For URL schemes, the public API, and Celery-settings compatibility, see [Configuration](/integrations/celery/reference/configuration); for worked examples and TLS recipes, see the [Configuration guide](/integrations/celery/how-to/configuration).
## broker\_transport\_options [#broker_transport_options]
Pass transport-level settings through `app.conf.broker_transport_options`. All nineteen keys are listed below.
```python title="broker_transport_options.py"
app.conf.broker_transport_options = {
"wait_timeout": 1,
"auth_token": "my-token",
"dead_letter_queue": "celery-dead-letters",
"max_receive_count": 3,
"client_id_prefix": "celery",
"tls_enabled": False,
"tls_cert_file": "/path/to/cert.pem",
"tls_key_file": "/path/to/key.pem",
"tls_ca_file": "/path/to/ca.pem",
"max_send_size": 4_194_304,
"max_receive_size": 4_194_304,
"connection_timeout": 10.0,
"purge_wait_seconds": 1,
"message_expiration": 3600,
"max_batch_size": 10,
"fanout_max_retries": 5,
"grpc_keepalive_time": 30,
"grpc_keepalive_timeout": 10,
"grpc_permit_without_calls": True,
}
```
| Option | Type | Default | Description |
| --------------------------- | --------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `wait_timeout` | `int` | `1` | Blocking receive timeout in seconds. Controls how long an internal `_get()` waits for a message before returning empty. Must be less than Celery's `drain_events` timeout (default 2s). Increase for higher-latency environments. |
| `auth_token` | `str \| None` | `None` | KubeMQ authentication token. Overrides the token in the broker URL if both are set. |
| `dead_letter_queue` | `str` | `""` | KubeMQ channel name for dead-letter messages. Messages that exceed `max_receive_count` are routed here. |
| `max_receive_count` | `int` | `0` | Maximum receive attempts before routing to the dead-letter queue. `0` disables the DLQ (messages redelivered indefinitely). Requires `dead_letter_queue` to be set. |
| `client_id_prefix` | `str` | `"celery"` | Prefix for KubeMQ client IDs. Each worker gets a unique ID: `{prefix}-queues-{random8}` and `{prefix}-pubsub-{random8}`. |
| `tls_enabled` | `bool` | `False` | Enable TLS for gRPC connections. Automatically set to `True` when using a `kubemq+tls://` URL scheme. Set explicitly to override URL-based detection. |
| `tls_cert_file` | `str` | `""` | Path to the client certificate file for mTLS authentication. |
| `tls_key_file` | `str` | `""` | Path to the client private key file for mTLS authentication. |
| `tls_ca_file` | `str` | `""` | Path to the CA certificate file for custom certificate-authority verification. |
| `max_send_size` | `int` | `4_194_304` | Maximum gRPC send message size in bytes (default 4 MB). Increase for large task payloads. |
| `max_receive_size` | `int` | `4_194_304` | Maximum gRPC receive message size in bytes (default 4 MB). Increase for large task results. |
| `connection_timeout` | `float \| None` | `None` | Initial gRPC connection timeout in seconds; `None` = SDK default. Read by both the transport and the result backend — see `examples/error_handling/reconnection.py`. |
| `purge_wait_seconds` | `int` | `1` | Seconds the server waits while purging a queue (an `ack_all` on the channel). The KubeMQ SDK's 60s default is too slow for empty-queue purges, so this defaults to `1`. Used by Celery's queue-reset / `_purge()` path. |
| `message_expiration` | `int` | `0` | Per-message TTL in seconds. Messages older than this are discarded by KubeMQ. `0` disables expiration. Maximum `86400` (24 hours). A task-level `expires` header takes precedence if set. |
| `max_batch_size` | `int` | `10` | Maximum messages per gRPC receive call. Higher values reduce round-trips but increase memory. Range: 1–100. |
| `fanout_max_retries` | `int` | `5` | Maximum re-subscription attempts when a fanout (Events) subscription encounters an error. Uses exponential backoff (1s, 2s, 4s, … max 30s). |
| `grpc_keepalive_time` | `int` | `30` | Seconds between gRPC keepalive pings. Prevents idle connections from being dropped by load balancers or firewalls. |
| `grpc_keepalive_timeout` | `int` | `10` | Seconds to wait for a keepalive ping response before considering the connection dead. |
| `grpc_permit_without_calls` | `bool` | `True` | Send keepalive pings even when there are no active RPCs. Keep `True` for long-lived connections that may be idle between task bursts. |
**`wait_timeout` must stay below Celery's `drain_events` timeout (default 2s).** The transport's blocking receive runs inside Celery's event-drain loop; if `wait_timeout` meets or exceeds the drain timeout, the loop can deadlock instead of cycling. The default `wait_timeout` of `1` is safe.
## result\_backend\_transport\_options [#result_backend_transport_options]
The [queue-peek result backend](/integrations/celery/how-to/result-backend) stores task results as KubeMQ Queue messages and retrieves them with a non-destructive peek. It runs its own KubeMQ client — configured independently of the broker — and accepts its own auth and TLS settings, gRPC message-size, keepalive, and connection-timeout tuning, plus two result-specific options. All thirteen keys are listed below.
```python title="result_backend_transport_options.py"
app.conf.result_backend = "kubemq://localhost:50000"
app.conf.result_backend_transport_options = {
"auth_token": "my-token",
"tls_enabled": False,
"tls_cert_file": "/path/to/cert.pem",
"tls_key_file": "/path/to/key.pem",
"tls_ca_file": "/path/to/ca.pem",
"max_send_size": 4_194_304,
"max_receive_size": 4_194_304,
"connection_timeout": 10.0,
"grpc_keepalive_time": 30,
"grpc_keepalive_timeout": 10,
"grpc_permit_without_calls": True,
"result_channel_prefix": "celery-result-",
"peek_timeout": 1,
}
```
| Option | Type | Default | Description |
| --------------------------- | --------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
| `auth_token` | `str \| None` | `None` | KubeMQ authentication token for the result backend connection. |
| `tls_enabled` | `bool` | `False` | Enable TLS for the result backend gRPC connection. |
| `tls_cert_file` | `str` | `""` | Path to the client certificate file for mTLS. |
| `tls_key_file` | `str` | `""` | Path to the client private key file for mTLS. |
| `tls_ca_file` | `str` | `""` | Path to the CA certificate file. |
| `max_send_size` | `int` | `4_194_304` | Maximum gRPC send message size in bytes (4 MB) for the result backend client. |
| `max_receive_size` | `int` | `4_194_304` | Maximum gRPC receive message size in bytes (4 MB) for the result backend client. |
| `connection_timeout` | `float \| None` | `None` | Initial gRPC connection timeout in seconds for the result backend client; `None` = SDK default. |
| `grpc_keepalive_time` | `int` | `30` | Seconds between gRPC keepalive pings on the result backend connection. |
| `grpc_keepalive_timeout` | `int` | `10` | Seconds to wait for a keepalive ping response before the result backend connection is considered dead. |
| `grpc_permit_without_calls` | `bool` | `True` | Send keepalive pings on the result backend connection even when there are no active RPCs. |
| `result_channel_prefix` | `str` | `"celery-result-"` | Prefix for per-task result channel names. Each task's result is stored on `{prefix}{task_id}` (e.g. `celery-result-`). |
| `peek_timeout` | `int` | `1` | Seconds the non-destructive peek waits for a result message before returning empty. |
### Result storage behavior [#result-storage-behavior]
* Results are stored on per-task channels named `celery-result-{task_id}`.
* Retrieval uses `peek_queue_messages()`, which is non-destructive — multiple callers can read the same result independently.
* Maximum result expiration is `86400` seconds (24 hours), a KubeMQ limitation. Celery's default `result_expires` of 24 hours matches the maximum exactly.
* State transitions (`PENDING → STARTED → SUCCESS`) purge and rewrite the result message.
* Chord support uses Celery's polling fallback via the `chord_unlock` task.
## See also [#see-also]