{"record":{"id":"dd9ba1f29fa3a3bc","repo":"lionsoul2014/ip2region","slug":"failed-to-determine-xdb-version-from-header-s","errorCode":null,"errorMessage":"failed to determine xdb version from header: %s","messagePattern":"failed to determine xdb version from header: (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"binding/nginx/src/ngx_http_ip2region_module.c","lineNumber":131,"sourceCode":"    }\n\n    ip2region_searcher->v_index = NULL;\n    ip2region_searcher->c_buffer = NULL;\n\n    // 检查XDB文件的版本信息以确定IP类型\n    xdb_header_t *header = xdb_load_header_from_file(db_path);\n    if (header == NULL) {\n        ngx_conf_log_error(NGX_LOG_EMERG, cf, 0,\n                           \"failed to load xdb header from: %s\", db_path);\n        if(ngx_http_ip2region_is_absolute_path(db_name) != NGX_OK) {\n            free(db_path);\n        }\n        return NGX_CONF_ERROR;\n    }\n\n    xdb_version_t *xdb_version = xdb_version_from_header(header);\n    if (xdb_version == NULL) {\n        ngx_conf_log_error(NGX_LOG_EMERG, cf, 0,\n                           \"failed to determine xdb version from header: %s\", db_path);\n        xdb_free_header((void *)header);\n        if(ngx_http_ip2region_is_absolute_path(db_name) != NGX_OK) {\n            free(db_path);\n        }\n        return NGX_CONF_ERROR;\n    }\n\n    // 验证XDB文件版本是否匹配\n    if (xdb_version->id != expected_version->id) {\n        ngx_conf_log_error(NGX_LOG_EMERG, cf, 0,\n                           \"%s expects %s xdb file, but got %s: %s\",\n                           directive_name, expected_version->name, xdb_version->name, db_path);\n        xdb_free_header((void *)header);\n        if(ngx_http_ip2region_is_absolute_path(db_name) != NGX_OK) {\n            free(db_path);\n        }\n        return NGX_CONF_ERROR;","sourceCodeStart":113,"sourceCodeEnd":149,"githubUrl":"https://github.com/lionsoul2014/ip2region/blob/c1a1fc7d5941760db3f8431dc05c48cf7f0e30a1/binding/nginx/src/ngx_http_ip2region_module.c#L113-L149","documentation":"At nginx startup, ip2region reads the first bytes of the xdb file to detect its IP format version (IPv2/IPv3/IPv4 structure). xdb_version_from_header returned NULL, meaning the header bytes do not match any known xdb version layout, so the module cannot initialize a searcher. This is a nginx conf-time (NGX_CONF_ERROR) failure that aborts nginx startup.","triggerScenarios":"The ip2region_db_file/ip2region_db_file_v6 directive points to a file whose header is corrupt, truncated (shorter than the header size), empty, or not an xdb file at all (e.g. a text file, HTML error page from a bad download, or a .xz/.gz archive that was not decompressed).","commonSituations":"Downloading the xdb with curl that saved an error page; an incomplete/ interrupted download; a file that was renamed but not the actual ip2region xdb; a corrupted copy on a mounted volume; using an old/different data format file.","solutions":["Verify the file is a genuine, complete ip2region xdb: check `file ip2region.xdb` and size, and re-download from the official data release.","Confirm the configured path in nginx.conf resolves to the intended file (no typos, correct root-relative resolution).","Regenerate or re-export the xdb with a maker tool from the same ip2region project version.","Check the file is not gzip/xz compressed; decompress it before use.","Confirm read permissions so the header can actually be read fully."],"exampleFix":"# before\nip2region_db_file /etc/nginx/data/ip2region.xdb.gz;\n# after\ngunzip /etc/nginx/data/ip2region.xdb.gz\nip2region_db_file /etc/nginx/data/ip2region.xdb;","handlingStrategy":"validation","validationCode":"#!/bin/bash\n# run before pointing nginx at the xdb\nf=/data/ip2region.xdb\n[ -s \"$f\" ] || { echo \"missing/empty xdb\"; exit 1; }\n[ $(stat -c%s \"$f\") -ge 256 ] || { echo \"xdb too small (truncated?)\"; exit 1; }\n# a real xdb starts with its structured header; reject compressed/text files\nfile \"$f\" | grep -Eqi 'gzip|xz|zip|ASCII text' && { echo 'not a raw xdb'; exit 1; }\necho \"xdb header looks loadable\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Checksum-verify xdb downloads before deployment.","Never configure a .gz/.xz archive path directly; decompress first.","Keep xdb files on stable, worker-readable paths.","Run `nginx -t` in CI so conf-time failures are caught before deploy."],"tags":["nginx","xdb","config-startup","file-format"],"backgroundTag":"invalid-xdb-file-header","analyzedSha":"c1a1fc7d5941760db3f8431dc05c48cf7f0e30a1","analyzedAt":"2026-09-02T16:58:39.988Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T21:17:11.164Z"}