n8n-io/n8n · error · ConfigurationError

Max payload size of {max_payload_size} bytes exceeds pipe me

Error message

Max payload size of {max_payload_size} bytes exceeds pipe message limit of {PIPE_MSG_MAX_SIZE} bytes. Reduce {ENV_MAX_PAYLOAD_SIZE}.

What it means

Thrown by TaskRunnerConfig.from_env when the max payload size read from N8N_RUNNERS_MAX_PAYLOAD_SIZE exceeds PIPE_MSG_MAX_SIZE, the maximum size of a single message that can be sent over the multiprocessing pipe between the runner and its subprocess. This prevents a configuration where the runner would accept payloads too large to ever transmit to the Python subprocess.

Source

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

        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,
            stdlib_allow=parse_allowlist(
                read_str_env(ENV_STDLIB_ALLOW, ""), ENV_STDLIB_ALLOW
            ),
            external_allow=parse_allowlist(
                read_str_env(ENV_EXTERNAL_ALLOW, ""), ENV_EXTERNAL_ALLOW
            ),

View on GitHub (pinned to 5ac6606e81)

Solutions

1. Reduce N8N_RUNNERS_MAX_PAYLOAD_SIZE to a value at or below PIPE_MSG_MAX_SIZE.
2. If you need to transfer larger data, split items across multiple tasks or reduce the data size upstream.
3. Check the PIPE_MSG_MAX_SIZE constant value to understand the ceiling.
4. Ensure you are specifying the value in bytes, not KB or MB.

Example fix

# before — payload size exceeds pipe limit
export N8N_RUNNERS_MAX_PAYLOAD_SIZE=1073741824  # 1 GiB, may exceed pipe limit
# after — keep within pipe limit
export N8N_RUNNERS_MAX_PAYLOAD_SIZE=67108864  # 64 MiB

from config.task_runner_config import PIPE_MSG_MAX_SIZE

max_payload = int(os.environ.get('N8N_RUNNERS_MAX_PAYLOAD_SIZE', str(PIPE_MSG_MAX_SIZE)))
if max_payload > PIPE_MSG_MAX_SIZE:
    raise ValueError(
        f'Max payload {max_payload} exceeds pipe limit {PIPE_MSG_MAX_SIZE}'
    )

from config.task_runner_config import ConfigurationError

try:
    config = TaskRunnerConfig.from_env()
except ConfigurationError as e:
    if 'payload size' in str(e).lower():
        print(f'Reduce N8N_RUNNERS_MAX_PAYLOAD_SIZE below the pipe limit')
    sys.exit(1)

When it happens

Trigger: The environment variable ENV_MAX_PAYLOAD_SIZE is set to a value (in bytes) greater than PIPE_MSG_MAX_SIZE. The check `if max_payload_size > PIPE_MSG_MAX_SIZE` fires in from_env. The message suggests reducing the ENV_MAX_PAYLOAD_SIZE value.

Common situations: Increasing the payload size to handle large items without realizing the pipe has a hard limit. Setting the value in MB or KB units when the code expects bytes. A default constant that was changed in a fork exceeding the pipe limit.

Related errors

• Environment variable N8N_RUNNERS_GRANT_TOKEN is required
• 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
• 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/1cc415afba96f5a4. Report an issue: GitHub.