{"record":{"id":"01731ae6f6660764","repo":"lionsoul2014/ip2region","slug":"failed-to-create-vector-index-cached-searcher-s","errorCode":null,"errorMessage":"failed to create vector index cached searcher: %s","messagePattern":"failed to create vector index cached searcher: (.+?)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"binding/nginx/src/ngx_http_ip2region_module.c","lineNumber":178,"sourceCode":"            }\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;\n        }\n    } else if (strcmp(cache_policy, \"content\") == 0) {\n        ip2region_searcher->c_buffer = xdb_load_content_from_file(db_path);\n        if (ip2region_searcher->c_buffer == NULL) {\n            ngx_conf_log_error(NGX_LOG_EMERG, cf, 0,\n                               \"failed to load xdb content: %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        }","sourceCodeStart":160,"sourceCodeEnd":196,"githubUrl":"https://github.com/lionsoul2014/ip2region/blob/c1a1fc7d5941760db3f8431dc05c48cf7f0e30a1/binding/nginx/src/ngx_http_ip2region_module.c#L160-L196","documentation":"nginx module init-time failure: the searcher could not be created with the vectorIndex cache policy because xdb_load_vector_index_from_file returned NULL — the vector index block could not be loaded from the configured db file (missing, unreadable, or too short). The directive returns NGX_CONF_ERROR and worker startup aborts.","triggerScenarios":"xdb_new_with_vector_index returns != 0: the xdb file cannot be opened/read by the current user, the file changed between loading the index and creating the searcher, or the loaded vector index does not correspond to the file's version/layout.","commonSituations":"Deploying a new xdb over the old path mid-reload so the cached vector index no longer matches; permissions changed between steps; mixing an index from one xdb with a different file version.","solutions":["Restart the reload/start so both the file and vector index are read from the same, unchanged xdb.","Ensure the file path is stable during deployment (atomic rename, not in-place overwrite).","Verify the file is readable by the nginx worker user.","Replace the xdb with a complete file of the matching version.","As a fallback, use cache policy \"file\" which does not require a preloaded index."],"exampleFix":"// before (bad deploy)\ncp new.ip2region.xdb /data/ip2region.xdb   # while nginx loading\n// after\nmv /data/ip2region.xdb.new /data/ip2region.xdb  # atomic, then nginx -s reload","handlingStrategy":"validation","validationCode":"#!/bin/bash\n# ensure the xdb is not mutated during (re)load and is worker-readable\nf=/data/ip2region.xdb\nlsof \"$f\" | grep -v nginx && echo \"WARN: file open by other writers\"\nsudo -u www-data test -r \"$f\" && echo readable || echo \"not readable by nginx user\"","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Deploy new xdb files atomically (write temp + mv), then reload nginx once.","Never swap the xdb while `nginx -s reload` is in flight.","Keep file permissions stable across deploys.","Use one xdb version consistently across all cache policies."],"tags":["nginx","xdb","vector-index","config-startup"],"backgroundTag":"xdb-version-mismatch","analyzedSha":"c1a1fc7d5941760db3f8431dc05c48cf7f0e30a1","analyzedAt":"2026-09-02T16:58:39.988Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-09T21:17:11.164Z"}