n8n-io/n8n · critical · ConfigurationError

Environment variable N8N_RUNNERS_GRANT_TOKEN is required

Error message

Environment variable N8N_RUNNERS_GRANT_TOKEN is required

What it means

Thrown by TaskRunnerConfig.from_env when the N8N_RUNNERS_GRANT_TOKEN environment variable is empty or unset. The grant token is the shared secret the Python runner uses to authenticate with the n8n task broker; without it the runner cannot register or receive tasks, so this is a hard startup requirement.

Source

Thrown at packages/@n8n/task-runner-python/src/config/task_runner_config.py:76

    max_payload_size: int
    task_timeout: int
    auto_shutdown_timeout: int
    graceful_shutdown_timeout: int
    stdlib_allow: set[str]
    external_allow: set[str]
    builtins_deny: set[str]
    env_deny: bool
    allow_transitive_imports: bool

    @property
    def is_auto_shutdown_enabled(self) -> bool:
        return self.auto_shutdown_timeout > 0

    @classmethod
    def from_env(cls):
        grant_token = read_str_env(ENV_GRANT_TOKEN, "")
        if not grant_token:
            raise ConfigurationError(
                "Environment variable N8N_RUNNERS_GRANT_TOKEN is required"
            )

        task_timeout = read_int_env(ENV_TASK_TIMEOUT, DEFAULT_TASK_TIMEOUT)
        if task_timeout <= 0:
            raise ConfigurationError(
                f"Task timeout must be positive, got {task_timeout}"
            )

        auto_shutdown_timeout = read_int_env(
            ENV_AUTO_SHUTDOWN_TIMEOUT, DEFAULT_AUTO_SHUTDOWN_TIMEOUT
        )
        if auto_shutdown_timeout < 0:
            raise ConfigurationError(
                f"Auto shutdown timeout must be non-negative, got {auto_shutdown_timeout}"
            )

        graceful_shutdown_timeout = read_int_env(

View on GitHub (pinned to 5ac6606e81)

Solutions

1. Set N8N_RUNNERS_GRANT_TOKEN to the same grant token configured on the n8n main process.
2. If running in Docker, add the environment variable to the runner container's env section.
3. If the token is generated dynamically by n8n, ensure the runner is started by n8n (not manually) so the token is passed.
4. Use the _FILE suffix variant (N8N_RUNNERS_GRANT_TOKEN_FILE) to read the token from a file if injecting via secrets.

Example fix

# before — missing or empty
# (N8N_RUNNERS_GRANT_TOKEN not set)
# after
export N8N_RUNNERS_GRANT_TOKEN='your-grant-token-here'

import os

grant_token = os.environ.get('N8N_RUNNERS_GRANT_TOKEN', '')
if not grant_token:
    # Also check _FILE variant
    token_file = os.environ.get('N8N_RUNNERS_GRANT_TOKEN_FILE')
    if token_file:
        grant_token = open(token_file).read().strip()
    if not grant_token:
        raise RuntimeError('N8N_RUNNERS_GRANT_TOKEN is required')

from config.task_runner_config import ConfigurationError

try:
    config = TaskRunnerConfig.from_env()
except ConfigurationError as e:
    if 'GRANT_TOKEN' in str(e):
        print('Set N8N_RUNNERS_GRANT_TOKEN to the token from n8n')
    sys.exit(1)

When it happens

Trigger: The Python task runner starts and read_str_env(ENV_GRANT_TOKEN, '') returns an empty string because the environment variable N8N_RUNNERS_GRANT_TOKEN is not set or is set to an empty value. The check `if not grant_token` fires immediately in from_env.

Common situations: Starting the Python runner without configuring the grant token. The token was set on the n8n main process but not propagated to the runner's environment. Docker/Kubernetes deployment missing the environment variable. Using the runner in external mode where the token must be explicitly provided.

Related errors

• Task timeout must be positive, got {task_timeout}
• Auto shutdown timeout must be non-negative, got {auto_shutdo
• Graceful shutdown timeout must be positive, got {graceful_sh
• Max payload size of {max_payload_size} bytes exceeds pipe me
• Failed to read {env_name}_FILE from file {file_path}: {e}

AI-assisted analysis of n8n-io/n8n@5ac6606e81 (2026-08-12). Data as JSON: /api/errors/d8e583878afba27e. Report an issue: GitHub.