{"record":{"id":"87f864b80673513e","repo":"n8n-io/n8n","slug":"graceful-shutdown-timeout-must-be-positive-got-g","errorCode":null,"errorMessage":"Graceful shutdown timeout must be positive, got {graceful_shutdown_timeout}","messagePattern":"Graceful shutdown timeout must be positive, got (.+?)","errorType":"validation","errorClass":"ConfigurationError","httpStatus":null,"severity":"error","filePath":"packages/@n8n/task-runner-python/src/config/task_runner_config.py","lineNumber":98,"sourceCode":"        task_timeout = read_int_env(ENV_TASK_TIMEOUT, DEFAULT_TASK_TIMEOUT)\n        if task_timeout <= 0:\n            raise ConfigurationError(\n                f\"Task timeout must be positive, got {task_timeout}\"\n            )\n\n        auto_shutdown_timeout = read_int_env(\n            ENV_AUTO_SHUTDOWN_TIMEOUT, DEFAULT_AUTO_SHUTDOWN_TIMEOUT\n        )\n        if auto_shutdown_timeout < 0:\n            raise ConfigurationError(\n                f\"Auto shutdown timeout must be non-negative, got {auto_shutdown_timeout}\"\n            )\n\n        graceful_shutdown_timeout = read_int_env(\n            ENV_GRACEFUL_SHUTDOWN_TIMEOUT, DEFAULT_SHUTDOWN_TIMEOUT\n        )\n        if graceful_shutdown_timeout <= 0:\n            raise ConfigurationError(\n                f\"Graceful shutdown timeout must be positive, got {graceful_shutdown_timeout}\"\n            )\n\n        max_payload_size = read_int_env(ENV_MAX_PAYLOAD_SIZE, DEFAULT_MAX_PAYLOAD_SIZE)\n        if max_payload_size > PIPE_MSG_MAX_SIZE:\n            raise ConfigurationError(\n                f\"Max payload size of {max_payload_size} bytes exceeds pipe message limit of {PIPE_MSG_MAX_SIZE} bytes. Reduce {ENV_MAX_PAYLOAD_SIZE}.\"\n            )\n\n        return cls(\n            grant_token=grant_token,\n            runner_id=read_str_env(ENV_RUNNER_ID, \"\"),\n            task_broker_uri=read_str_env(ENV_TASK_BROKER_URI, DEFAULT_TASK_BROKER_URI),\n            max_concurrency=read_int_env(ENV_MAX_CONCURRENCY, DEFAULT_MAX_CONCURRENCY),\n            max_payload_size=max_payload_size,\n            task_timeout=task_timeout,\n            auto_shutdown_timeout=auto_shutdown_timeout,\n            graceful_shutdown_timeout=graceful_shutdown_timeout,","sourceCodeStart":80,"sourceCodeEnd":116,"githubUrl":"https://github.com/n8n-io/n8n/blob/5ac6606e81f67bb9534255570cd4e86fd8101eee/packages/@n8n/task-runner-python/src/config/task_runner_config.py#L80-L116","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set N8N_RUNNERS_GRACEFUL_SHUTDOWN_TIMEOUT to a positive integer (e.g. 30 for 30 seconds).","If you want minimal grace, use 1 rather than 0.","Check the environment variable for accidental zero or negative values.","Restart the runner after correcting the value."],"exampleFix":"# before\nexport N8N_RUNNERS_GRACEFUL_SHUTDOWN_TIMEOUT=0\n# after\nexport N8N_RUNNERS_GRACEFUL_SHUTDOWN_TIMEOUT=30","handlingStrategy":"validation","validationCode":"graceful_timeout = int(os.environ.get('N8N_RUNNERS_GRACEFUL_SHUTDOWN_TIMEOUT', '30'))\nif graceful_timeout <= 0:\n    raise ValueError(f'Graceful shutdown timeout must be positive, got {graceful_timeout}')","typeGuard":null,"tryCatchPattern":"from config.task_runner_config import ConfigurationError\n\ntry:\n    config = TaskRunnerConfig.from_env()\nexcept ConfigurationError as e:\n    print(f'Fix configuration: {e}')\n    sys.exit(1)","preventionTips":["Set graceful shutdown timeout to at least 5-10 seconds to allow in-flight tasks to complete.","Never use 0 or negative values — use 1 for minimal grace.","Validate timeout values in deployment templates."],"tags":["task-runner","python","configuration","timeout","shutdown","startup"],"backgroundTag":null,"analyzedSha":"5ac6606e81f67bb9534255570cd4e86fd8101eee","analyzedAt":"2026-08-12T05:26:35.080Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}