{"record":{"id":"3b481d424911e92b","repo":"nginx/nginx","slug":"ngx-log-emerg-3b481d","errorCode":"NGX_LOG_EMERG","errorMessage":"unknown thread pool \\\"%V\\\" in %s:%ui","messagePattern":"unknown thread pool \\\\\"%V\\\\\" in (.+?):%ui","errorType":"console","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"src/core/ngx_thread_pool.c","lineNumber":444,"sourceCode":"    tpp = tcf->pools.elts;\n\n    for (i = 0; i < tcf->pools.nelts; i++) {\n\n        if (tpp[i]->threads) {\n            continue;\n        }\n\n        if (tpp[i]->name.len == ngx_thread_pool_default.len\n            && ngx_strncmp(tpp[i]->name.data, ngx_thread_pool_default.data,\n                           ngx_thread_pool_default.len)\n               == 0)\n        {\n            tpp[i]->threads = 32;\n            tpp[i]->max_queue = 65536;\n            continue;\n        }\n\n        ngx_log_error(NGX_LOG_EMERG, cycle->log, 0,\n                      \"unknown thread pool \\\"%V\\\" in %s:%ui\",\n                      &tpp[i]->name, tpp[i]->file, tpp[i]->line);\n\n        return NGX_CONF_ERROR;\n    }\n\n    return NGX_CONF_OK;\n}\n\n\nstatic char *\nngx_thread_pool(ngx_conf_t *cf, ngx_command_t *cmd, void *conf)\n{\n    ngx_str_t          *value;\n    ngx_uint_t          i;\n    ngx_thread_pool_t  *tp;\n\n    value = cf->args->elts;","sourceCodeStart":426,"sourceCodeEnd":462,"githubUrl":"https://github.com/nginx/nginx/blob/3f6f7824d4e2eb1ac37dec76683d525ac0ff521c/src/core/ngx_thread_pool.c#L426-L462","documentation":"After config parsing, ngx_thread_pool_init_conf() walks every pool entry created by ngx_thread_pool_add(); entries with threads still 0 were referenced but never defined by a 'thread_pool' directive. The implicit 'default' pool is auto-sized to 32 threads / 65536 queue; any other undefined name aborts startup with this EMERG - 'nginx -t' fails before any worker starts. The %s:%ui in the message is the file and line of the first reference (e.g. the 'aio threads=name;' line recorded in ngx_thread_pool_add).","triggerScenarios":"'aio threads=bigdisk;' in a location but no 'thread_pool bigdisk threads=N;' at main context; renaming a pool in one place only; generated configs dropping the thread_pool stanza.","commonSituations":"Adding 'aio threads=<pool>' from documentation examples without the matching directive; splitting configs into includes where the thread_pool stanza gets lost; copy-paste between environments.","solutions":["Add the missing directive at main context: thread_pool <name> threads=N [max_queue=M];","Fix the reference if the pool exists under a different name - names are matched exactly (case-sensitive)","Run nginx -t and jump to the %s:%ui in the message - it points at the exact line that referenced the unknown pool"],"exampleFix":"# before\nhttp {\n    server {\n        location /files/ {\n            root /data;\n            aio threads=bigdisk;   # referenced, never defined\n        }\n    }\n}\n\n# after\nthread_pool bigdisk threads=32 max_queue=65536;   # main context\nhttp {\n    server {\n        location /files/ {\n            root /data;\n            aio threads=bigdisk;\n        }\n    }\n}","handlingStrategy":"validation","validationCode":"# CI check: every pool referenced by aio threads= must be defined\nrefs=$(nginx -T 2>/dev/null | grep -hoE 'aio +threads=[A-Za-z0-9_]+' | sed -E 's/.*threads=//')\nfor r in $refs; do\n  [ \"$r\" = \"default\" ] && continue\n  nginx -T 2>/dev/null | grep -qE \"^thread_pool +$r +threads=\" || {\n    echo \"undefined thread pool: $r\"; exit 1; }\ndone\nnginx -t","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep the thread_pool directive and its aio threads= references in the same file or included together","Always run nginx -t in CI and deploy hooks - this error is config-time and fully preventable","Remember the implicit sizing only covers the literal pool name 'default'"],"tags":["nginx","thread-pool","config","aio-threads","startup-failure"],"backgroundTag":"unknown-config-reference","analyzedSha":"3f6f7824d4e2eb1ac37dec76683d525ac0ff521c","analyzedAt":"2026-08-22T03:09:46.447Z","schemaVersion":2},"datasetVersion":"2026-08-22T04:17:13.399Z"}