lionsoul2014/ip2region · error · InvalidConfigException

SetXdbInputStream could ONLY be used with cachePolicy = Conf

Error message

SetXdbInputStream could ONLY be used with cachePolicy = Config.BufferCache

What it means

ConfigBuilder.build() refuses to proceed when an xdb InputStream was set via setXdbInputStream but the cachePolicy is not Config.BufferCache. Streaming input can only be fully loaded into memory, so other cache policies (which require random access to a file) are incompatible. The library deliberately does not silently override the policy so the developer knows what they are doing.

Source

Thrown at binding/java/src/main/java/org/lionsoul/ip2region/service/ConfigBuilder.java:93

    }

    public ConfigBuilder setSearchers(int searchers) {
        this.searchers = searchers;
        return this;
    }

    public ConfigBuilder setFairLock(boolean fairLock) {
        this.fairLock = fairLock;
        return this;
    }

    private Config build(Version ipVersion) throws IOException, XdbException, InvalidConfigException {
        if (xdbInputStream == null) {
            // everyting is fine
        } else if (cachePolicy != Config.BufferCache) {
            // @Note: we can't directly rewrite the cachePolicy to Config.BufferCache.
            // you must know what you are doing.
            throw new InvalidConfigException("SetXdbInputStream could ONLY be used with cachePolicy = Config.BufferCache");
        } else {
            // 1, load the content buffer
            final LongByteArray cBuffer = Searcher.loadContentFromInputStream(xdbInputStream, cacheSliceBytes);

            // 2, load the header
            final Header header = Searcher.loadHeaderFromBuffer(cBuffer);

            // 3, verify the xdb from the buffer
            Searcher.verify(header, cBuffer.length());

            // create the config without xdbFile and vIndex
            return new Config(cachePolicy, ipVersion, null, header, null, cBuffer, searchers, fairLock);
        }

        // load the header and the cache buffer
        final File xdbFile;
        if (this.xdbFile != null) {
            xdbFile = this.xdbFile;

View on GitHub (pinned to c1a1fc7d59)

Solutions

1. Set the cache policy to Config.BufferCache via ConfigBuilder.cachePolicy(Config.BufferCache) when using setXdbInputStream
2. Remove the setXdbInputStream call and instead use setXdbFile/setXdbPath if you need vector-index or other file-backed policies
3. If you must keep the stream, read the stream content yourself and pass the resulting byte buffer instead

Example fix

// before
builder.setXdbInputStream(is).cachePolicy(Config.VectorIndex).asV4();
// after
builder.setXdbInputStream(is).cachePolicy(Config.BufferCache).asV4();

if (usingInputStream && cachePolicy != Config.BufferCache) {
    throw new IllegalStateException("setXdbInputStream requires cachePolicy=Config.BufferCache");
}

try {
    ip2Region = new ConfigBuilder().setXdbInputStream(is).cachePolicy(Config.BufferCache).asV4();
} catch (InvalidConfigException e) {
    log.error("stream init requires BufferCache policy", e);
}

When it happens

Trigger: Calling ConfigBuilder.setXdbInputStream(...) (or its fluent variant) and then build()/asV4()/asV6() while cachePolicy is Config.VectorIndex or Config.Content (any policy other than BufferCache).

Common situations: Loading an xdb from a classpath resource, URL or non-file stream while copying a cachePolicy from file-based sample code; switching from file to stream input without removing the old policy.

Related errors

• invalid cache policy `${name}`
• ip verison not match: xdb file ${xdbFile.getAbsolutePath()}
• Both xdbFile and xdbPath is null
• invalid byte ip address with length=${ipBytes.length}
• invalid ip address (${version.name} expected)

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