From 61913f079cbaafe27511e5f6b5c6f75770a22570 Mon Sep 17 00:00:00 2001 From: Crazelu Date: Thu, 24 Sep 2026 17:12:51 +0100 Subject: [PATCH 1/8] docs: document futureCall.enabled config --- .../06-scheduling/05-configuration.md | 25 +++++++++++++++++-- .../lookups/configuration-reference.md | 1 + 2 files changed, 24 insertions(+), 2 deletions(-) diff --git a/docs/06-concepts/06-scheduling/05-configuration.md b/docs/06-concepts/06-scheduling/05-configuration.md index 2d346446..4a73313f 100644 --- a/docs/06-concepts/06-scheduling/05-configuration.md +++ b/docs/06-concepts/06-scheduling/05-configuration.md @@ -1,5 +1,5 @@ --- -description: Future call settings cover execution, concurrency, the scan interval, and broken-call handling, set in config files or environment variables. +description: Future call settings cover enabling future calls, execution, concurrency, the scan interval, and broken-call handling, set in config files or environment variables. --- # Configuration @@ -8,6 +8,7 @@ You configure future calls in your Serverpod config files or through environment | Option | Default | Controls | | --- | --- | --- | +| `futureCall.enabled` | `true` | Whether future calls can be scheduled and executed. | | `futureCallExecutionEnabled` | `true` | Whether this server runs future calls at all. | | `futureCall.concurrencyLimit` | `1` | How many calls may run at once. | | `futureCall.scanInterval` | `5000` | How often, in milliseconds, the server checks for due calls. | @@ -18,15 +19,35 @@ You configure future calls in your Serverpod config files or through environment futureCallExecutionEnabled: true futureCall: + enabled: true # default concurrencyLimit: 1 # default scanInterval: 5000 # default, in milliseconds ``` ## Execution options +### Disable future calls entirely + +The `futureCall.enabled` option turns future calls off completely. It is `true` by default. When set to `false`, the server does not create a future call manager, so calls can neither be scheduled nor executed. Use it when your project does not use future calls. + +```yaml +futureCall: + enabled: false +``` + +You can also set it with the `SERVERPOD_FUTURE_CALL_ENABLED` environment variable, which takes precedence over the config file. + +:::warning +Trying to schedule future calls when `futureCall.enabled` is set to false throws an error. +::: + +:::info +Future calls require a database. Without one, they are disabled regardless of this option. +::: + ### Enable or disable execution -The `futureCallExecutionEnabled` option turns future call execution on or off for a server. It is `true` by default. Set it to `false` in environments where background tasks should not run, such as a staging server where you want to test API behavior without triggering scheduled work. +The `futureCallExecutionEnabled` option turns future call execution on or off for a server. It is `true` by default. Unlike `futureCall.enabled`, it does not stop calls from being scheduled; they are stored and run by any server that has execution enabled. Set it to `false` in environments where background tasks should not run, such as a staging server where you want to test API behavior without triggering scheduled work. ```yaml futureCallExecutionEnabled: false diff --git a/docs/06-concepts/lookups/configuration-reference.md b/docs/06-concepts/lookups/configuration-reference.md index ab08a01d..14d10fd2 100644 --- a/docs/06-concepts/lookups/configuration-reference.md +++ b/docs/06-concepts/lookups/configuration-reference.md @@ -72,6 +72,7 @@ Ports, hosts, and connection settings for the API, Insights, and web servers, th | SERVERPOD_SESSION_LOG_RETENTION_COUNT | sessionLogs.retentionCount | - | Maximum number of session log entries to keep. Set to null to disable count-based cleanup. Defaults to `100000` only when `sessionLogs` is not configured at all. See [Purge old records](../operations/logging#purge-old-records). | | SERVERPOD_SESSION_CONSOLE_LOG_ENABLED | sessionLogs.consoleEnabled | - | Enables or disables logging session data to the console. Defaults to `true` if no database is configured or the run mode is `development`, otherwise `false`. | | SERVERPOD_SESSION_CONSOLE_LOG_FORMAT | sessionLogs.consoleLogFormat | - | The format for console logging of session data. Valid options are `text` and `json`. Defaults to `text` for run mode `development`, otherwise `json`. | +| SERVERPOD_FUTURE_CALL_ENABLED | futureCall.enabled | true | Enables or disables future calls entirely. When disabled, future calls can neither be scheduled nor executed. | | SERVERPOD_FUTURE_CALL_EXECUTION_ENABLED | futureCallExecutionEnabled | true | Enables or disables the execution of future calls. | | SERVERPOD_FUTURE_CALL_CONCURRENCY_LIMIT | futureCall.concurrencyLimit | 1 | The maximum number of concurrent future calls allowed. If the value is negative or null, no limit is applied. | | SERVERPOD_FUTURE_CALL_SCAN_INTERVAL | futureCall.scanInterval | 5000 | The interval in milliseconds for scanning future calls | From ce00a81718ed7d39e2cb316ce9cc489d99693c32 Mon Sep 17 00:00:00 2001 From: Crazelu Date: Thu, 24 Sep 2026 17:20:54 +0100 Subject: [PATCH 2/8] docs: document futureCall.executionEnabled config --- docs/06-concepts/06-scheduling/05-configuration.md | 10 +++++----- docs/06-concepts/07-operations/06-scalability.md | 2 +- docs/06-concepts/lookups/configuration-reference.md | 2 +- 3 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/06-concepts/06-scheduling/05-configuration.md b/docs/06-concepts/06-scheduling/05-configuration.md index 4a73313f..896ddec3 100644 --- a/docs/06-concepts/06-scheduling/05-configuration.md +++ b/docs/06-concepts/06-scheduling/05-configuration.md @@ -9,17 +9,16 @@ You configure future calls in your Serverpod config files or through environment | Option | Default | Controls | | --- | --- | --- | | `futureCall.enabled` | `true` | Whether future calls can be scheduled and executed. | -| `futureCallExecutionEnabled` | `true` | Whether this server runs future calls at all. | +| `futureCall.executionEnabled` | `true` | Whether this server runs future calls at all. | | `futureCall.concurrencyLimit` | `1` | How many calls may run at once. | | `futureCall.scanInterval` | `5000` | How often, in milliseconds, the server checks for due calls. | | `futureCall.checkBrokenCalls` | unset | Whether to scan for broken calls on startup. | | `futureCall.deleteBrokenCalls` | `false` | Whether to delete broken calls that are found. | ```yaml -futureCallExecutionEnabled: true - futureCall: enabled: true # default + executionEnabled: true # default concurrencyLimit: 1 # default scanInterval: 5000 # default, in milliseconds ``` @@ -47,10 +46,11 @@ Future calls require a database. Without one, they are disabled regardless of th ### Enable or disable execution -The `futureCallExecutionEnabled` option turns future call execution on or off for a server. It is `true` by default. Unlike `futureCall.enabled`, it does not stop calls from being scheduled; they are stored and run by any server that has execution enabled. Set it to `false` in environments where background tasks should not run, such as a staging server where you want to test API behavior without triggering scheduled work. +The `executionEnabled` option turns future call execution on or off for a server. It is `true` by default. Unlike `futureCall.enabled`, it does not stop calls from being scheduled; they are stored and run by any server that has execution enabled. Set it to `false` in environments where background tasks should not run, such as a staging server where you want to test API behavior without triggering scheduled work. ```yaml -futureCallExecutionEnabled: false +futureCall: + executionEnabled: false ``` ### Concurrency limit diff --git a/docs/06-concepts/07-operations/06-scalability.md b/docs/06-concepts/07-operations/06-scalability.md index c91cc269..5dcef483 100644 --- a/docs/06-concepts/07-operations/06-scalability.md +++ b/docs/06-concepts/07-operations/06-scalability.md @@ -30,7 +30,7 @@ Use roles so request capacity and background work do not share the same scaling dart run bin/main.dart --mode production --role serverless ``` -Schedule a separate process in the `maintenance` role (for example once per minute) when request nodes run as `serverless`. On pure request nodes you can also set `futureCallExecutionEnabled` to `false`; see [Future call configuration](../scheduling/configuration). +Schedule a separate process in the `maintenance` role (for example once per minute) when request nodes run as `serverless`. On pure request nodes you can also set `futureCall.executionEnabled` to `false`; see [Future call configuration](../scheduling/configuration). ## Offload CPU work to isolates diff --git a/docs/06-concepts/lookups/configuration-reference.md b/docs/06-concepts/lookups/configuration-reference.md index 14d10fd2..96491a9d 100644 --- a/docs/06-concepts/lookups/configuration-reference.md +++ b/docs/06-concepts/lookups/configuration-reference.md @@ -73,7 +73,7 @@ Ports, hosts, and connection settings for the API, Insights, and web servers, th | SERVERPOD_SESSION_CONSOLE_LOG_ENABLED | sessionLogs.consoleEnabled | - | Enables or disables logging session data to the console. Defaults to `true` if no database is configured or the run mode is `development`, otherwise `false`. | | SERVERPOD_SESSION_CONSOLE_LOG_FORMAT | sessionLogs.consoleLogFormat | - | The format for console logging of session data. Valid options are `text` and `json`. Defaults to `text` for run mode `development`, otherwise `json`. | | SERVERPOD_FUTURE_CALL_ENABLED | futureCall.enabled | true | Enables or disables future calls entirely. When disabled, future calls can neither be scheduled nor executed. | -| SERVERPOD_FUTURE_CALL_EXECUTION_ENABLED | futureCallExecutionEnabled | true | Enables or disables the execution of future calls. | +| SERVERPOD_FUTURE_CALL_EXECUTION_ENABLED | futureCall.executionEnabled | true | Enables or disables the execution of future calls. | | SERVERPOD_FUTURE_CALL_CONCURRENCY_LIMIT | futureCall.concurrencyLimit | 1 | The maximum number of concurrent future calls allowed. If the value is negative or null, no limit is applied. | | SERVERPOD_FUTURE_CALL_SCAN_INTERVAL | futureCall.scanInterval | 5000 | The interval in milliseconds for scanning future calls | | SERVERPOD_FUTURE_CALL_CHECK_BROKEN_CALLS | futureCall.checkBrokenCalls | - | Enables or disables the automatic check for broken future calls on startup. By default, the server performs an automatic check if there are less than 1000 calls in the database. | From 7d86c38260d7312d6890cc3708a2b39b2ce891b5 Mon Sep 17 00:00:00 2001 From: Lucky Ebere <58946834+Crazelu@users.noreply.github.com> Date: Fri, 25 Sep 2026 10:39:17 +0100 Subject: [PATCH 3/8] Update docs/06-concepts/07-operations/06-scalability.md Co-authored-by: Jamiu Okanlawon <50176100+developerjamiu@users.noreply.github.com> --- docs/06-concepts/07-operations/06-scalability.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/06-concepts/07-operations/06-scalability.md b/docs/06-concepts/07-operations/06-scalability.md index 5dcef483..62bcd101 100644 --- a/docs/06-concepts/07-operations/06-scalability.md +++ b/docs/06-concepts/07-operations/06-scalability.md @@ -30,7 +30,7 @@ Use roles so request capacity and background work do not share the same scaling dart run bin/main.dart --mode production --role serverless ``` -Schedule a separate process in the `maintenance` role (for example once per minute) when request nodes run as `serverless`. On pure request nodes you can also set `futureCall.executionEnabled` to `false`; see [Future call configuration](../scheduling/configuration). +Schedule a separate process in the `maintenance` role (for example once per minute) when request nodes run as `serverless`. On pure request nodes you can also disable execution with the `SERVERPOD_FUTURE_CALL_EXECUTION_ENABLED` environment variable set to `false`, so the maintenance process, which reads the same config file, keeps running calls; see [Future call configuration](../scheduling/configuration). ## Offload CPU work to isolates From 7ab8ede54d1aaac3cc6a7a4c0113a6b13f36289a Mon Sep 17 00:00:00 2001 From: Lucky Ebere <58946834+Crazelu@users.noreply.github.com> Date: Fri, 25 Sep 2026 10:39:34 +0100 Subject: [PATCH 4/8] Update docs/06-concepts/06-scheduling/05-configuration.md Co-authored-by: Jamiu Okanlawon <50176100+developerjamiu@users.noreply.github.com> --- docs/06-concepts/06-scheduling/05-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/06-concepts/06-scheduling/05-configuration.md b/docs/06-concepts/06-scheduling/05-configuration.md index 896ddec3..314dc89e 100644 --- a/docs/06-concepts/06-scheduling/05-configuration.md +++ b/docs/06-concepts/06-scheduling/05-configuration.md @@ -46,7 +46,7 @@ Future calls require a database. Without one, they are disabled regardless of th ### Enable or disable execution -The `executionEnabled` option turns future call execution on or off for a server. It is `true` by default. Unlike `futureCall.enabled`, it does not stop calls from being scheduled; they are stored and run by any server that has execution enabled. Set it to `false` in environments where background tasks should not run, such as a staging server where you want to test API behavior without triggering scheduled work. +The `futureCall.executionEnabled` option turns future call execution on or off for a server. It is `true` by default. Unlike `futureCall.enabled`, it does not stop calls from being scheduled; they are stored and run by any server that has execution enabled. Set it to `false` in environments where background tasks should not run, such as a staging server where you want to test API behavior without triggering scheduled work. ```yaml futureCall: From aa3236fcd94db6d23c8b56c753ca48612d8037b3 Mon Sep 17 00:00:00 2001 From: Lucky Ebere <58946834+Crazelu@users.noreply.github.com> Date: Fri, 25 Sep 2026 10:41:30 +0100 Subject: [PATCH 5/8] Update docs/06-concepts/06-scheduling/05-configuration.md Co-authored-by: Jamiu Okanlawon <50176100+developerjamiu@users.noreply.github.com> --- docs/06-concepts/06-scheduling/05-configuration.md | 10 +--------- 1 file changed, 1 insertion(+), 9 deletions(-) diff --git a/docs/06-concepts/06-scheduling/05-configuration.md b/docs/06-concepts/06-scheduling/05-configuration.md index 314dc89e..9cc074e8 100644 --- a/docs/06-concepts/06-scheduling/05-configuration.md +++ b/docs/06-concepts/06-scheduling/05-configuration.md @@ -34,15 +34,7 @@ futureCall: enabled: false ``` -You can also set it with the `SERVERPOD_FUTURE_CALL_ENABLED` environment variable, which takes precedence over the config file. - -:::warning -Trying to schedule future calls when `futureCall.enabled` is set to false throws an error. -::: - -:::info -Future calls require a database. Without one, they are disabled regardless of this option. -::: +If you schedule a call while it is off, the server throws a `StateError` with the message `FutureCalls is not initialized.` Future calls also need a database. Without one, they are off regardless of this option. ### Enable or disable execution From 7fb5dbda28fcfdff32696692435ed01e514374ab Mon Sep 17 00:00:00 2001 From: Lucky Ebere <58946834+Crazelu@users.noreply.github.com> Date: Fri, 25 Sep 2026 10:41:45 +0100 Subject: [PATCH 6/8] Update docs/06-concepts/06-scheduling/05-configuration.md Co-authored-by: Jamiu Okanlawon <50176100+developerjamiu@users.noreply.github.com> --- docs/06-concepts/06-scheduling/05-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/06-concepts/06-scheduling/05-configuration.md b/docs/06-concepts/06-scheduling/05-configuration.md index 9cc074e8..f01994fa 100644 --- a/docs/06-concepts/06-scheduling/05-configuration.md +++ b/docs/06-concepts/06-scheduling/05-configuration.md @@ -27,7 +27,7 @@ futureCall: ### Disable future calls entirely -The `futureCall.enabled` option turns future calls off completely. It is `true` by default. When set to `false`, the server does not create a future call manager, so calls can neither be scheduled nor executed. Use it when your project does not use future calls. +The `futureCall.enabled` option turns future calls off completely. It is `true` by default. When set to `false`, calls can neither be scheduled nor executed. Use it when your project does not use future calls. ```yaml futureCall: From 13ba77b73fed60db494b93f506468e1d7b05ded8 Mon Sep 17 00:00:00 2001 From: Lucky Ebere <58946834+Crazelu@users.noreply.github.com> Date: Fri, 25 Sep 2026 10:41:51 +0100 Subject: [PATCH 7/8] Update docs/06-concepts/06-scheduling/05-configuration.md Co-authored-by: Jamiu Okanlawon <50176100+developerjamiu@users.noreply.github.com> --- docs/06-concepts/06-scheduling/05-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/06-concepts/06-scheduling/05-configuration.md b/docs/06-concepts/06-scheduling/05-configuration.md index f01994fa..d1370d0f 100644 --- a/docs/06-concepts/06-scheduling/05-configuration.md +++ b/docs/06-concepts/06-scheduling/05-configuration.md @@ -9,7 +9,7 @@ You configure future calls in your Serverpod config files or through environment | Option | Default | Controls | | --- | --- | --- | | `futureCall.enabled` | `true` | Whether future calls can be scheduled and executed. | -| `futureCall.executionEnabled` | `true` | Whether this server runs future calls at all. | +| `futureCall.executionEnabled` | `true` | Whether this server runs due calls. Scheduling still works. | | `futureCall.concurrencyLimit` | `1` | How many calls may run at once. | | `futureCall.scanInterval` | `5000` | How often, in milliseconds, the server checks for due calls. | | `futureCall.checkBrokenCalls` | unset | Whether to scan for broken calls on startup. | From 015ec2c1e952ee8c881f26605c74ec8f2c88ecda Mon Sep 17 00:00:00 2001 From: Crazelu Date: Fri, 25 Sep 2026 10:52:41 +0100 Subject: [PATCH 8/8] docs: document futureCall.enabled outside "Execution options" section --- docs/06-concepts/06-scheduling/05-configuration.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/06-concepts/06-scheduling/05-configuration.md b/docs/06-concepts/06-scheduling/05-configuration.md index d1370d0f..508922a6 100644 --- a/docs/06-concepts/06-scheduling/05-configuration.md +++ b/docs/06-concepts/06-scheduling/05-configuration.md @@ -23,9 +23,7 @@ futureCall: scanInterval: 5000 # default, in milliseconds ``` -## Execution options - -### Disable future calls entirely +## Disable future calls The `futureCall.enabled` option turns future calls off completely. It is `true` by default. When set to `false`, calls can neither be scheduled nor executed. Use it when your project does not use future calls. @@ -36,6 +34,8 @@ futureCall: If you schedule a call while it is off, the server throws a `StateError` with the message `FutureCalls is not initialized.` Future calls also need a database. Without one, they are off regardless of this option. +## Execution options + ### Enable or disable execution The `futureCall.executionEnabled` option turns future call execution on or off for a server. It is `true` by default. Unlike `futureCall.enabled`, it does not stop calls from being scheduled; they are stored and run by any server that has execution enabled. Set it to `false` in environments where background tasks should not run, such as a staging server where you want to test API behavior without triggering scheduled work.