n8n-io/n8n · error · ConfigurationError

Auto shutdown timeout must be non-negative, got {auto_shutdo

Error message

Auto shutdown timeout must be non-negative, got {auto_shutdown_timeout}

What it means

Thrown by TaskRunnerConfig.from_env when the auto-shutdown timeout read from N8N_RUNNERS_AUTO_SHUTDOWN_TIMEOUT is negative. A value of 0 disables auto-shutdown (is_auto_shutdown_enabled returns False); negative values are meaningless and rejected. The timeout controls how long the runner idles before shutting down when no tasks arrive.

Source

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

    @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(
            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(

View on GitHub (pinned to 5ac6606e81)

Solutions

1. Set N8N_RUNNERS_AUTO_SHUTDOWN_TIMEOUT to 0 to disable auto-shutdown, or a positive number of seconds.
2. Check the environment variable for stray negative signs.
3. Restart the runner after correcting the value.

Example fix

# before
export N8N_RUNNERS_AUTO_SHUTDOWN_TIMEOUT=-1
# after — disable auto-shutdown
export N8N_RUNNERS_AUTO_SHUTDOWN_TIMEOUT=0
# after — shut down after 300s idle
export N8N_RUNNERS_AUTO_SHUTDOWN_TIMEOUT=300

auto_shutdown = int(os.environ.get('N8N_RUNNERS_AUTO_SHUTDOWN_TIMEOUT', '0'))
if auto_shutdown < 0:
    raise ValueError(f'Auto shutdown timeout must be >= 0, got {auto_shutdown}')

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_AUTO_SHUTDOWN_TIMEOUT is set to a negative number. The check `if auto_shutdown_timeout < 0` fires in from_env. The property is_auto_shutdown_enabled checks `self.auto_shutdown_timeout > 0`, so 0 is a valid 'disabled' sentinel.

Common situations: Accidentally setting a negative value through a typo or miscalculation. Misunderstanding that 0 means 'disabled' and trying negative values to express the same intent. Deployment template arithmetic producing a negative result.

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}
• Graceful shutdown timeout must be positive, got {graceful_sh
• 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/3a885baaa83827ec. Report an issue: GitHub.