n8n-io/n8n · error · ConfigurationError

Graceful shutdown timeout must be positive, got {graceful_sh

Error message

Graceful shutdown timeout must be positive, got {graceful_shutdown_timeout}

What it means

Thrown by TaskRunnerConfig.from_env when the graceful shutdown timeout read from N8N_RUNNERS_GRACEFUL_SHUTDOWN_TIMEOUT is zero or negative. The graceful shutdown timeout is how long the runner waits for in-flight tasks to complete during a shutdown before forcing termination; a non-positive value would mean no grace period at all, which risks losing task results.

Source

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

        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(
            ENV_GRACEFUL_SHUTDOWN_TIMEOUT, DEFAULT_SHUTDOWN_TIMEOUT
        )
        if graceful_shutdown_timeout <= 0:
            raise ConfigurationError(
                f"Graceful shutdown timeout must be positive, got {graceful_shutdown_timeout}"
            )

        max_payload_size = read_int_env(ENV_MAX_PAYLOAD_SIZE, DEFAULT_MAX_PAYLOAD_SIZE)
        if max_payload_size > PIPE_MSG_MAX_SIZE:
            raise ConfigurationError(
                f"Max payload size of {max_payload_size} bytes exceeds pipe message limit of {PIPE_MSG_MAX_SIZE} bytes. Reduce {ENV_MAX_PAYLOAD_SIZE}."
            )

        return cls(
            grant_token=grant_token,
            runner_id=read_str_env(ENV_RUNNER_ID, ""),
            task_broker_uri=read_str_env(ENV_TASK_BROKER_URI, DEFAULT_TASK_BROKER_URI),
            max_concurrency=read_int_env(ENV_MAX_CONCURRENCY, DEFAULT_MAX_CONCURRENCY),
            max_payload_size=max_payload_size,
            task_timeout=task_timeout,
            auto_shutdown_timeout=auto_shutdown_timeout,
            graceful_shutdown_timeout=graceful_shutdown_timeout,

View on GitHub (pinned to 5ac6606e81)

Solutions

1. Set N8N_RUNNERS_GRACEFUL_SHUTDOWN_TIMEOUT to a positive integer (e.g. 30 for 30 seconds).
2. If you want minimal grace, use 1 rather than 0.
3. Check the environment variable for accidental zero or negative values.
4. Restart the runner after correcting the value.

Example fix

# before
export N8N_RUNNERS_GRACEFUL_SHUTDOWN_TIMEOUT=0
# after
export N8N_RUNNERS_GRACEFUL_SHUTDOWN_TIMEOUT=30

graceful_timeout = int(os.environ.get('N8N_RUNNERS_GRACEFUL_SHUTDOWN_TIMEOUT', '30'))
if graceful_timeout <= 0:
    raise ValueError(f'Graceful shutdown timeout must be positive, got {graceful_timeout}')

from config.task_runner_config import ConfigurationError

try:
    config = TaskRunnerConfig.from_env()
except ConfigurationError as e:
    print(f'Fix configuration: {e}')
    sys.exit(1)

When it happens

Trigger: The environment variable ENV_GRACEFUL_SHUTDOWN_TIMEOUT is set to 0 or a negative number. The check `if graceful_shutdown_timeout <= 0` fires in from_env.

Common situations: Setting the timeout to 0 intending 'immediate shutdown' (use a small positive value like 1 instead). Accidental negative value from a deployment script. Overriding the DEFAULT_SHUTDOWN_TIMEOUT constant incorrectly in a custom build.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• Task timeout must be positive, got {task_timeout}
• Auto shutdown timeout must be non-negative, got {auto_shutdo
• Environment variable N8N_RUNNERS_GRANT_TOKEN is required
• 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/87f864b80673513e. Report an issue: GitHub.