What causes "invalid cache policy `${name}`" in lionsoul2014/ip2region?

Use one of the accepted names: "file"/"none", "vectorindex"/"vindex"/"vindexcache", or "content"/"buffercache" (case-insensitive).

lionsoul2014/ip2region · error · InvalidConfigException

invalid cache policy `${name}`

Error message

invalid cache policy `${name}`

What it means

cachePolicyFromName maps a user-supplied policy string (case-insensitive) to a cache-policy constant: none/file, vectorindex/vindex/vindexcache, or content/buffercache. Any other value throws InvalidConfigException listing the offending name.

Source

Thrown at binding/java/src/main/java/org/lionsoul/ip2region/service/Config.java:102

            sb.append("c_buffer: null, ");
        } else {
            sb.append("c_buffer: {bytes: ").append(cBuffer.length()).append("},");
        }
        sb.append("searchers:").append(searchers);
        sb.append('}');
        return sb.toString();
    }

    public static final int cachePolicyFromName(String name) throws InvalidConfigException {
        final String lName = name.toLowerCase();
        if (lName.equals("file") || lName.equals("nocache")) {
            return NoCache;
        } else if (lName.equals("vectorindex") || lName.equals("vindex") || lName.equals("vindexcache")) {
            return VIndexCache;
        } else if (lName.equals("content") || lName.equals("buffercache")) {
            return BufferCache;
        } else {
            throw new InvalidConfigException("invalid cache policy `" + name + "`");
        }
    }
}

View on GitHub (pinned to c1a1fc7d59)

Solutions

Use one of the accepted names: "file"/"none", "vectorindex"/"vindex"/"vindexcache", or "content"/"buffercache" (case-insensitive).
Fix the typo in the configuration property/argument supplying the policy name.
Validate user/CLI input against the allowed set before passing it in, and fall back to a default (e.g. VIndexCache) when absent.

Example fix

// before
Searcher.cachePolicyFromName("full-cache"); // throws
// after
String policy = (name == null) ? "vectorindex" : name.toLowerCase();
Searcher.cachePolicyFromName(policy);

Defensive patterns

Strategy: validation

Validate before calling

private static final Set<String> VALID = Set.of("file","none","vectorindex","vindex","vindexcache","content","buffercache");
if (policy != null && !VALID.contains(policy.toLowerCase()))
  throw new IllegalArgumentException("invalid cache policy " + policy);

Try / catch

try {
  policy = cachePolicyFromName(name);
} catch (InvalidConfigException e) {
  log.warn("unknown cache policy {}, falling back to vectorindex", name);
  policy = cachePolicyFromName("vectorindex");
}

Prevention

Centralize the policy string in a constant/enum instead of scattering literals in config.
List accepted values in your configuration docs/schema (e.g. application.yml comments).
Validate config at startup (fail fast) rather than when the first searcher is built.

When it happens

Trigger: Passing a policy string like "memory", "full", "VECTOR" (with extra chars), "vecindex" (typo), or a null/empty name to cachePolicyFromName or wherever a policy string is configured (Searcher config, CLI flags, Spring properties).

Common situations: Typos in application.yml/env vars; porting from docs of another ip2region binding that uses different policy names; users inventing intuitive names like 'cache' or 'ram'.

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/a194dfa9098d2eaf. Report an issue: GitHub.