lionsoul2014/ip2region · error · Exception

invalid xdb structure version `{$header['version']}`

Error message

invalid xdb structure version `{$header['version']}`

What it means

PHP versionFromHeader: the header's structure version is neither 2.0 (IPv4-only) nor 3.0, so the loaded file is not a recognized xdb database — usually corruption, truncation, or the wrong file.

Source

Thrown at binding/php/xdb/Searcher.class.php:90

        if ($name == "V4" || $name == "IPv4") {
            return IPv4::default();
        } else if ($name == "V6" || $name == "IPv6") {
            return IPv6::default();
        } else {
            throw new Exception("invalid verstion name `{$ver_name}`");
        }
    }

    // version parse from header
    public static function versionFromHeader($header) {
        // Old structure 2.0 with IPv4 supports ONLY
        if ($header['version'] == Structure_20) {
            return IPv4::default();
        }

        // structure 3.0 after IPv6 supporting
        if ($header['version'] != Structure_30) {
            throw new Exception("invalid xdb structure version `{$header['version']}`");
        }

        if ($header['ipVersion'] == IPv4VersionNo) {
            return IPv4::default();
        } else if ($header['ipVersion'] == IPv6VersionNo) {
            return IPv6::default();
        } else {
            throw new Exception("invalid ip version number `{$header['ipVersion']}`");
        }
    }

    // binary string chars implode with space
    public static function bytesToString($buff, $offset, $length) {
        $sb = [];
        for ($i = 0; $i < $length; $i++) {
            $sb[] = ord($buff[$offset+$i]) & 0xFF;
        }
        return '['.implode(' ', $sb).']';

View on GitHub (pinned to c1a1fc7d59)

Solutions

1. Point the searcher at a valid, current-generation xdb file
2. Re-generate the database with the official maker
3. Check file integrity (size, first bytes) after copying/downloading

When it happens

Trigger: Thrown at binding/php/xdb/Searcher.class.php:90 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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