What causes "invalid variable name \"%V\"" in nginx/nginx?

Prefix the target variable with '$': map $uri $newvar { ... }

NGX_LOG_EMERG

NGX_LOG_EMERG

Error message

invalid variable name \"%V\"

What it means

Validation in the map directive handler of ngx_http_map_module.c: the third argument to 'map <source> <target> {' must be the target variable name and must start with '$'. After stripping the '$', the name is registered via ngx_http_add_variable(). A missing or malformed leading '$' is rejected with NGX_LOG_EMERG.

Source

Thrown at src/http/modules/ngx_http_map_module.c:222

        return NGX_CONF_ERROR;
    }

    value = cf->args->elts;

    ngx_memzero(&ccv, sizeof(ngx_http_compile_complex_value_t));

    ccv.cf = cf;
    ccv.value = &value[1];
    ccv.complex_value = &map->value;

    if (ngx_http_compile_complex_value(&ccv) != NGX_OK) {
        return NGX_CONF_ERROR;
    }

    name = value[2];

    if (name.data[0] != '$') {
        ngx_conf_log_error(NGX_LOG_EMERG, cf, 0,
                           "invalid variable name \"%V\"", &name);
        return NGX_CONF_ERROR;
    }

    name.len--;
    name.data++;

    var = ngx_http_add_variable(cf, &name, NGX_HTTP_VAR_CHANGEABLE);
    if (var == NULL) {
        return NGX_CONF_ERROR;
    }

    var->get_handler = ngx_http_map_variable;
    var->data = (uintptr_t) map;

    pool = ngx_create_pool(NGX_DEFAULT_POOL_SIZE, cf->log);
    if (pool == NULL) {
        return NGX_CONF_ERROR;

View on GitHub (pinned to 3f6f7824d4)

Solutions

Prefix the target variable with '$': map $uri $newvar { ... }
Quote configs processed by envsubst or shell heredocs so '$' is preserved (e.g. use quoted heredoc <<'EOF' or escape \$)
Check the map directive has exactly two arguments before the block: source and $target
Validate with nginx -t

Example fix

# before
map $uri backend_flag { default 0; }
# after
map $uri $backend_flag { default 0; }

Defensive patterns

Strategy: validation

Validate before calling

# second map argument must start with '$'
awk '/^[ \t]*map[ \t]/ && /\{/ { if ($3 !~ /^\$/) print FILENAME":"FNR": map target must be $var: "$3 }' /etc/nginx/nginx.conf /etc/nginx/conf.d/*.conf
nginx -t

Try / catch

if ! nginx -t 2>err.log; then cat err.log; exit 1; fi

Prevention

Both map arguments are variables and start with '$'
Use quoted heredocs or escape \$ when configs pass through envsubst/shell
Add a pre-commit grep for map lines missing '$'

When it happens

Trigger: A map directive whose second parameter does not begin with '$': 'map $uri /path {...}', 'map $uri path {...}', 'map $uri ${var} {' style typos, or a map line where the target variable was accidentally deleted.

Common situations: Writing the target as a plain identifier out of habit from rewrite-map syntaxes of other servers, templating that strips the '$' (e.g. shell or envsubst expanding $newvar inside the config), or copy-paste that drops the variable.

Related errors

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