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

Prefix the first argument with $: auth_request_set $authuser $upstream_http_x_user;

NGX_LOG_EMERG

NGX_LOG_EMERG

Error message

invalid variable name \"%V\"

What it means

The auth_request_set directive registers a variable to be filled from the auth subrequest; its first argument must be a variable reference starting with '$'. If it does not, nginx logs EMERG during configuration parsing and aborts. The '$' is stripped and the remainder is compiled as the variable name.

Source

Thrown at src/http/modules/ngx_http_auth_request_module.c:401

    return NGX_CONF_OK;
}


static char *
ngx_http_auth_request_set(ngx_conf_t *cf, ngx_command_t *cmd, void *conf)
{
    ngx_http_auth_request_conf_t *arcf = conf;

    ngx_str_t                         *value;
    ngx_http_variable_t               *v;
    ngx_http_auth_request_variable_t  *av;
    ngx_http_compile_complex_value_t   ccv;

    value = cf->args->elts;

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

    value[1].len--;
    value[1].data++;

    if (arcf->vars == NGX_CONF_UNSET_PTR) {
        arcf->vars = ngx_array_create(cf->pool, 1,
                                      sizeof(ngx_http_auth_request_variable_t));
        if (arcf->vars == NULL) {
            return NGX_CONF_ERROR;
        }
    }

    av = ngx_array_push(arcf->vars);
    if (av == NULL) {
        return NGX_CONF_ERROR;

View on GitHub (pinned to 3f6f7824d4)

Solutions

Prefix the first argument with $: auth_request_set $authuser $upstream_http_x_user;
Run 'nginx -t' to catch it before reload.
In envsubst/Helm templates escape the dollar as $$ so it survives rendering.

Example fix

# before
auth_request_set authuser $upstream_http_x_user;

# after
auth_request_set $authuser $upstream_http_x_user;

Defensive patterns

Strategy: validation

Validate before calling

nginx -t 2>&1 | grep 'invalid variable name'   # fail the pipeline if present
# reject auth_request_set lines lacking the dollar sign before deploy
grep -nE 'auth_request_set\s+[^$]' /etc/nginx/**/*.conf

Prevention

Always write auth_request_set $name value;.
Escape dollars in envsubst/Helm templates ($$) so rendering does not strip them.
Run 'nginx -t' as a CI gate for every config change.

When it happens

Trigger: Writing 'auth_request_set authuser $upstream_http_x_user;' (missing $), or quoting that drops the dollar sign; copy-paste from docs where $ was rendered literally.

Common situations: First-time auth_request users assuming the argument is a plain name; templating systems (Helm, envsubst) consuming $ - in templates use $$ to escape.

Related errors

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