{"record":{"id":"31355be2a77cbf55","repo":"nginx/nginx","slug":"ngx-log-emerg-31355b","errorCode":"NGX_LOG_EMERG","errorMessage":"load balancing method does not support resolving names at run time in upstream \\\"%V\\\" in %s:%ui","messagePattern":"load balancing method does not support resolving names at run time in upstream \\\\\"%V\\\\\" in (.+?):%ui","errorType":"console","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"src/stream/ngx_stream_upstream_round_robin.c","lineNumber":96,"sourceCode":"            if (server[i].host.len) {\n                r++;\n                continue;\n            }\n#endif\n\n            n += server[i].naddrs;\n            w += server[i].naddrs * server[i].weight;\n\n            if (!server[i].down) {\n                t += server[i].naddrs;\n            }\n        }\n\n#if (NGX_STREAM_UPSTREAM_ZONE)\n        if (us->shm_zone) {\n\n            if (resolve && !(us->flags & NGX_STREAM_UPSTREAM_MODIFY)) {\n                ngx_log_error(NGX_LOG_EMERG, cf->log, 0,\n                              \"load balancing method does not support\"\n                              \" resolving names at run time in\"\n                              \" upstream \\\"%V\\\" in %s:%ui\",\n                              &us->host, us->file_name, us->line);\n                return NGX_ERROR;\n            }\n\n            cscf = ngx_stream_conf_get_module_srv_conf(cf,\n                                                       ngx_stream_core_module);\n\n            if (us->resolver == NULL) {\n                us->resolver = cscf->resolver;\n            }\n\n            /*\n             * Without \"resolver_timeout\" in stream{} the merged value is unset.\n             */\n            ngx_conf_merge_msec_value(us->resolver_timeout,","sourceCodeStart":78,"sourceCodeEnd":114,"githubUrl":"https://github.com/nginx/nginx/blob/3f6f7824d4e2eb1ac37dec76683d525ac0ff521c/src/stream/ngx_stream_upstream_round_robin.c#L78-L114","documentation":"When a stream upstream lives in shared memory (`zone` directive) and at least one `server` entry needs run-time name resolution (`resolve` parameter, or `service=` which implies it), nginx requires the selected load-balancing method to declare NGX_STREAM_UPSTREAM_MODIFY, because worker processes must be able to use a peer set that changes as DNS answers arrive. All built-in methods (round robin, hash, least_conn, least_time, random) set this flag; a third-party balancer that does not causes this EMERG at upstream initialization and nginx refuses to start.","triggerScenarios":"A config combining `zone <name> <size>;` and `server host:port resolve;` (or `service=...`) inside `upstream {}` together with a third-party load-balancing directive whose handler does not OR NGX_STREAM_UPSTREAM_MODIFY into uscf->flags. The check is `resolve && !(us->flags & NGX_STREAM_UPSTREAM_MODIFY)` in ngx_stream_upstream_init_round_robin.","commonSituations":"Deploying custom or vendor balancing modules (custom consistent-hash, entropy-based selectors, commercial plugins) into a service-mesh style zone-based upstream that relies on dynamic DNS; the module was written before run-time re-resolution existed in the stream upstream.","solutions":["Switch the upstream to a built-in method (round robin, hash, least_conn, random) which declares run-time modify support","Patch the third-party module so its directive handler sets NGX_STREAM_UPSTREAM_MODIFY in uscf->flags (only safe if its peer.init genuinely tolerates peers added/removed at run time)","Drop `resolve`/`service=` from the servers and use addresses fixed at configuration time"],"exampleFix":"# before\nupstream backend {\n    zone backend 1m;\n    server api.example.com:443 resolve;\n    my_custom_balancer;   # third-party module, no NGX_STREAM_UPSTREAM_MODIFY\n}\n\n# after\nupstream backend {\n    zone backend 1m;\n    server api.example.com:443 resolve;\n    least_conn;\n}","handlingStrategy":"validation","validationCode":"nginx -t -c /etc/nginx/nginx.conf 2>&1 | grep -E 'does not support|resolving names|emerg'","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Before combining a third-party balancer with `zone` + `resolve`, check its directive handler sets NGX_STREAM_UPSTREAM_MODIFY in uscf->flags","Test the exact combination (zone + resolve + balancer) in staging with `nginx -t`; the failure is config-time, so it is cheap to catch","Prefer built-in methods for upstreams whose membership changes at run time"],"tags":["nginx","stream","upstream","load-balancing","shared-memory","dns","resolve","configuration"],"backgroundTag":"upstream-runtime-resolution-unsupported","analyzedSha":"3f6f7824d4e2eb1ac37dec76683d525ac0ff521c","analyzedAt":"2026-08-22T03:09:46.447Z","schemaVersion":2},"datasetVersion":"2026-08-22T04:17:13.399Z"}