{"record":{"id":"51c01fff77857377","repo":"lionsoul2014/ip2region","slug":"failed-to-load-vector-index-from-s","errorCode":null,"errorMessage":"failed to load vector index from: %s","messagePattern":"failed to load vector index from: (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"binding/nginx/src/ngx_http_ip2region_module.c","lineNumber":166,"sourceCode":"        }\n        return NGX_CONF_ERROR;\n    }\n\n    if (strcmp(cache_policy, \"file\") == 0) {\n        err = xdb_new_with_file_only(xdb_version, &ip2region_searcher->searcher, db_path);\n        xdb_free_header((void *)header);\n        if (err != 0) {\n            ngx_conf_log_error(NGX_LOG_EMERG, cf, 0,\n                               \"failed to create searcher: %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    } else if (strcmp(cache_policy, \"vectorIndex\") == 0) {\n        ip2region_searcher->v_index = xdb_load_vector_index_from_file(db_path);\n        if (ip2region_searcher->v_index == NULL) {\n            ngx_conf_log_error(NGX_LOG_EMERG, cf, 0,\n                               \"failed to load vector index from: %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        err = xdb_new_with_vector_index(xdb_version, &ip2region_searcher->searcher, db_path, ip2region_searcher->v_index);\n        xdb_free_header((void *)header);\n        if (err != 0) {\n            ngx_conf_log_error(NGX_LOG_EMERG, cf, 0,\n                               \"failed to create vector index cached searcher: %s\", db_path);\n            xdb_free_vector_index((void *)ip2region_searcher->v_index);\n            if(ngx_http_ip2region_is_absolute_path(db_name) != NGX_OK) {\n                free(db_path);\n            }\n            return NGX_CONF_ERROR;","sourceCodeStart":148,"sourceCodeEnd":184,"githubUrl":"https://github.com/lionsoul2014/ip2region/blob/c1a1fc7d5941760db3f8431dc05c48cf7f0e30a1/binding/nginx/src/ngx_http_ip2region_module.c#L148-L184","documentation":"With cache_policy \"vectorIndex\", the module first loads the vector index portion of the xdb into memory via xdb_load_vector_index_from_file. NULL means that read/allocation failed, so a vector-index-cached searcher cannot be built.","triggerScenarios":"xdb_load_vector_index_from_file returns NULL: the file disappeared or became unreadable between the header check and this call, the file is truncated (vector index region missing), or memory allocation for the index failed.","commonSituations":"Truncated/incomplete xdb download (header OK but index region cut off); disk full or malloc failure under memory limits; the file being replaced atomically while nginx is reloading config.","solutions":["Re-download/re-export a complete xdb and verify its size against the official release.","Confirm the nginx user can read the file and the disk is not full (`df -h`).","If memory-constrained, switch cache policy to \"file\" which avoids loading the vector index.","Ensure the file is not being overwritten while nginx starts (stage-and-rename deployments)."],"exampleFix":"ip2region_cache_policy vectorIndex;\n# after (if memory constrained)\nip2region_cache_policy file;","handlingStrategy":"validation","validationCode":"#!/bin/bash\n# full-file sanity: a truncated xdb cannot yield a vector index\nf=/data/ip2region.xdb\n[ $(stat -c%s \"$f\") -eq $(curl -sIL https://official-url/ip2region.xdb | awk '/content-length/{print $2}' | tr -d '\\r') ] || echo \"size mismatch: xdb is truncated\"\nfree -m | awk 'NR==2{if ($7 < 512) print \"WARN: low available memory for vector index\"}'","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Verify xdb size/checksum after download.","Avoid overwriting the xdb in place; deploy via atomic rename.","Monitor free memory on hosts using vectorIndex/content policies.","Fall back to policy \"file\" on memory-constrained hosts."],"tags":["nginx","xdb","vector-index","memory","file-io"],"backgroundTag":"xdb-file-truncated","analyzedSha":"c1a1fc7d5941760db3f8431dc05c48cf7f0e30a1","analyzedAt":"2026-09-02T16:58:39.988Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T21:17:11.164Z"}