lionsoul2014/ip2region · error · Exception

searchers must be > 0

Error message

searchers must be > 0

What it means

The Cangjie Config constructor validates that the searcher pool size (searchers) is a positive integer. A pool of zero or fewer searchers could never serve a lookup, so construction fails fast with this exception.

Source

Thrown at binding/cangjie/src/service/config.cj:23

// Cache policy constants - match Searcher modes
public let FileOnly: Int64 = 0
public let VectorIndex: Int64 = 1
public let ContentBuff: Int64 = 2

// Config holds xdb file configuration and pre-loaded data for creating Searcher instances
public class Config {
    public let cachePolicy: Int64
    public let ipVersion: Version
    public let xdbPath: String
    public let header: Header
    public let vIndex: Array<Byte>
    public let cBuffer: Array<Byte>
    public let searchers: Int64

    public init(cachePolicy: Int64, ipVersion: Version, xdbPath: String, searchers: Int64) {
        if (searchers <= 0) {
            throw Exception("searchers must be > 0")
        }

        this.cachePolicy = cachePolicy
        this.ipVersion = ipVersion
        this.xdbPath = xdbPath
        this.searchers = searchers

        let content = File.readFrom(Path(xdbPath))
        this.header = newHeaderFromBytes(content)

        // Verify IP version matches
        let detectedVersion = versionFromHeader(this.header)
        if (detectedVersion.id != ipVersion.id) {
            throw Exception("xdb file IP version mismatch: expected ${ipVersion.name}, got ${detectedVersion.name}")
        }

        if (cachePolicy == VectorIndex) {
            this.vIndex = loadVectorIndex(content)

View on GitHub (pinned to c1a1fc7d59)

Solutions

1. Pass a positive searchers value (e.g. number of worker threads you intend to run)
2. Clamp the configured value before constructing: max(1, configuredValue)
3. Fix the config file/env var supplying the pool size
4. Choose the pool size to match expected concurrency (e.g. CPU core count)

Example fix

// before
let cfg = Config(cachePolicy, ver, xdbPath, envSearchers) // envSearchers = 0
// after
let n = if (envSearchers > 0) { envSearchers } else { 4 }
let cfg = Config(cachePolicy, ver, xdbPath, n)

// Cangjie: clamp before constructing Config
let n = if (rawSearchers > 0) { rawSearchers } else { 4 }
// then: Config(cachePolicy, ipVersion, xdbPath, n)

func poolSizeOk(n: Int64): Bool { return n > 0 }

try {
    let cfg = Config(cachePolicy, ver, xdbPath, searchers)
} catch (e: Exception) {
    log.error("config rejected: ${e.message}")
    return InitResult.Failed
}

When it happens

Trigger: Creating Config (or the service built on it) with searchers <= 0 — e.g. reading the pool size from config that defaults to 0, an env var parsed as 0, or an arithmetic result of 0.

Common situations: Config file with 'searchers = 0', missing environment variable yielding 0 after toInt64, or computing pool size as cpus - overhead which floors to 0 on small machines.

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

• xdb file IP version mismatch: expected ${ipVersion.name}, go
• SearcherPool is closing

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