What causes "invalid cache policy, options: file/vectorIndex/content" in lionsoul2014/ip2region?

Set the policy to exactly one of: file, vectorIndex, content (lowercase, no quotes/whitespace).

lionsoul2014/ip2region · critical

invalid cache policy, options: file/vectorIndex/content

Error message

invalid cache policy, options: file/vectorIndex/content

What it means

The ip2region_cache_policy directive received a value that is not one of the three supported strings: "file", "vectorIndex", or "content". The module falls into the else branch, frees resources, and rejects the configuration.

Source

Thrown at binding/nginx/src/ngx_http_ip2region_module.c:210

            if(ngx_http_ip2region_is_absolute_path(db_name) != NGX_OK) {
                free(db_path);
            }
            return NGX_CONF_ERROR;
        }

        err = xdb_new_with_buffer(xdb_version, &ip2region_searcher->searcher, ip2region_searcher->c_buffer);
        xdb_free_header((void *)header);
        if (err != 0) {
            ngx_conf_log_error(NGX_LOG_EMERG, cf, 0,
                               "failed to create content cached searcher: %s", db_path);
            xdb_free_content((void *)ip2region_searcher->c_buffer);
            if(ngx_http_ip2region_is_absolute_path(db_name) != NGX_OK) {
                free(db_path);
            }
            return NGX_CONF_ERROR;
        }
    } else {
        ngx_conf_log_error(NGX_LOG_EMERG, cf, 0,
                           "invalid cache policy, options: file/vectorIndex/content");
        xdb_free_header((void *)header);
        if(ngx_http_ip2region_is_absolute_path(db_name) != NGX_OK) {
            free(db_path);
        }
        return NGX_CONF_ERROR;
    }

    if(ngx_http_ip2region_is_absolute_path(db_name) != NGX_OK) {
        free(db_path);
    }

    return (char *)ip2region_searcher;
}


static char *
ngx_http_ip2region_init(ngx_conf_t *cf, ngx_command_t *cmd,

View on GitHub (pinned to c1a1fc7d59)

Solutions

Set the policy to exactly one of: file, vectorIndex, content (lowercase, no quotes/whitespace).
Fix the typo — e.g. vector_index -> vectorIndex, Content -> content.
Run `nginx -t` to validate the config before reload.
Check the README of the nginx binding for the exact accepted values.

Example fix

# before
ip2region_cache_policy vector_index;
# after
ip2region_cache_policy vectorIndex;

Defensive patterns

Strategy: validation

Validate before calling

# nginx.conf lint before reload
case "$(awk '/ip2region_cache_policy/{gsub(";","");print $2}' nginx.conf)" in
  file|vectorIndex|content) echo OK ;;
  *) echo "invalid ip2region_cache_policy (use file|vectorIndex|content)"; exit 1 ;;
esac

Prevention

Memorize the three accepted values: file, vectorIndex, content — exact lowercase.
Run `nginx -t` as a CI gate for every config change.
Copy config snippets from the nginx binding's own README, not other-language docs.
Avoid trailing whitespace/variables feeding the directive.

When it happens

Trigger: Any misspelled or wrong-case value in nginx.conf, e.g. `ip2region_cache_policy Content;`, `content ` with trailing whitespace via variable, `vector_index`, `none`, or an empty value.

Common situations: Typos when copying examples from docs for other bindings (some bindings use different policy names); Nginx variable interpolation yielding an unexpected string; case sensitivity mistakes.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

AI-assisted analysis of lionsoul2014/ip2region@c1a1fc7d59 (2026-09-02). Data as JSON: /api/errors/30260a657c733c6c. Report an issue: GitHub.