NGX_LOG_EMERG

NGX_LOG_EMERG

Error message

load balancing method does not support resolving names at run time in upstream \"%V\" in %s:%ui

What it means

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.

Source

Thrown at src/stream/ngx_stream_upstream_round_robin.c:96

            if (server[i].host.len) {
                r++;
                continue;
            }
#endif

            n += server[i].naddrs;
            w += server[i].naddrs * server[i].weight;

            if (!server[i].down) {
                t += server[i].naddrs;
            }
        }

#if (NGX_STREAM_UPSTREAM_ZONE)
        if (us->shm_zone) {

            if (resolve && !(us->flags & NGX_STREAM_UPSTREAM_MODIFY)) {
                ngx_log_error(NGX_LOG_EMERG, cf->log, 0,
                              "load balancing method does not support"
                              " resolving names at run time in"
                              " upstream \"%V\" in %s:%ui",
                              &us->host, us->file_name, us->line);
                return NGX_ERROR;
            }

            cscf = ngx_stream_conf_get_module_srv_conf(cf,
                                                       ngx_stream_core_module);

            if (us->resolver == NULL) {
                us->resolver = cscf->resolver;
            }

            /*
             * Without "resolver_timeout" in stream{} the merged value is unset.
             */
            ngx_conf_merge_msec_value(us->resolver_timeout,

View on GitHub (pinned to 3f6f7824d4)

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

Example fix

# before
upstream backend {
    zone backend 1m;
    server api.example.com:443 resolve;
    my_custom_balancer;   # third-party module, no NGX_STREAM_UPSTREAM_MODIFY
}

# after
upstream backend {
    zone backend 1m;
    server api.example.com:443 resolve;
    least_conn;
}

Defensive patterns

Strategy: validation

Validate before calling

nginx -t -c /etc/nginx/nginx.conf 2>&1 | grep -E 'does not support|resolving names|emerg'

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of nginx/nginx@3f6f7824d4 (2026-08-22). Data as JSON: /api/errors/31355be2a77cbf55. Report an issue: GitHub.