{"record":{"id":"23494446faafd7ea","repo":"deepinsight/insightface","slug":"archive-not-initialized","errorCode":null,"errorMessage":"Archive not initialized","messagePattern":"Archive not initialized","errorType":"exception","errorClass":"std::runtime_error","httpStatus":null,"severity":"critical","filePath":"cpp-package/inspireface/cpp/inspireface/runtime_module/launch.cpp","lineNumber":93,"sourceCode":"\n// Constructor implementation\nLaunch::Launch() : pImpl(std::make_unique<Impl>()) {}\n\n// Destructor implementation\nLaunch::~Launch() = default;\n\nstd::shared_ptr<Launch> Launch::GetInstance() {\n    std::lock_guard<std::mutex> lock(Impl::mutex_);\n    if (!Impl::instance_) {\n        Impl::instance_ = std::shared_ptr<Launch>(new Launch());\n    }\n    return Impl::instance_;\n}\n\nInspireArchive& Launch::getMArchive() {\n    std::lock_guard<std::mutex> lock(pImpl->mutex_);\n    if (!pImpl->m_archive_) {\n        throw std::runtime_error(\"Archive not initialized\");\n    }\n    return *(pImpl->m_archive_);\n}\n\nint32_t Launch::Load(const std::string& path) {\n    std::lock_guard<std::mutex> lock(pImpl->mutex_);\n#if defined(ISF_ENABLE_TENSORRT)\n    int32_t support_cuda;\n    auto ret = CheckCudaUsability(&support_cuda);\n    if (ret != HSUCCEED) {\n        INSPIRE_LOGE(\"An error occurred while checking CUDA device support. Please ensure that your environment supports CUDA!\");\n        return ret;\n    }\n    if (!support_cuda) {\n        INSPIRE_LOGE(\"Your environment does not support CUDA! Please ensure that your environment supports CUDA!\");\n        return HERR_DEVICE_CUDA_NOT_SUPPORT;\n    }\n#endif","sourceCodeStart":75,"sourceCodeEnd":111,"githubUrl":"https://github.com/deepinsight/insightface/blob/7fadd420c2351d0ffa8cac403421c1a3ed733365/cpp-package/inspireface/cpp/inspireface/runtime_module/launch.cpp#L75-L111","documentation":"Launch::getMArchive() returns the process-wide InspireArchive that holds all loaded resource files, and throws std::runtime_error(\"Archive not initialized\") when it is called before Launch::Load() has successfully created the archive (pImpl->m_archive_ is still null). It is an initialization-order guard: any component requesting models/resources must do so only after the launch/load sequence completes.","triggerScenarios":"Calling getMArchive() (or higher-level APIs that fetch resources from the archive) before Launch::Load(path) has run or before it has finished successfully; a failed Load (bad pack path, corrupt archive) leaving m_archive_ null and a subsequent call still trying to use the archive; running two sessions where the second queries the archive after a reset/destroy; calling from another thread before load completes due to missing synchronization in user code.","commonSituations":"Integrating InspireFace into a service and accidentally invoking feature/landmark APIs before the initial Load in the startup sequence; Load failing silently (wrong resource path after deployment) and the next API call throwing this instead of the root-cause error; calling from a callback that fires during initialization, before the archive pointer is assigned.","solutions":["Ensure Launch::Load(resource_path) is called and returns success before any API that touches the archive (feature extraction, landmark, etc.).","Check the return value of Load: if it failed, log and stop instead of continuing to use the session — the root cause is usually a bad/corrupt resource path.","Verify the resource pack path is absolute or correctly resolved relative to the process CWD at runtime.","Serialize initialization: perform Load once at startup and only start worker threads/callbacks that call the API after Load completes."],"exampleFix":"// before\nauto& archive = launch.getMArchive(); // throws \"Archive not initialized\"\nlaunch.Load(\"res/inspireface.bundle\");\n// after\nint32_t rc = launch.Load(\"res/inspireface.bundle\");\nif (rc != 0) { /* log and abort startup */ }\nauto& archive = launch.getMArchive(); // safe","handlingStrategy":"validation","validationCode":"int32_t rc = launch.Load(resource_path);\nif (rc != 0) {\n    // abort startup; archive is definitely not ready\n}\n// only after successful Load call APIs that use the archive","typeGuard":null,"tryCatchPattern":"try {\n    auto& archive = launch.getMArchive();\n} catch (const std::runtime_error& e) {\n    if (std::string(e.what()) == \"Archive not initialized\") {\n        // initialization-order bug: call Load() first, then retry\n    } else throw;\n}","preventionTips":["Call Load once during startup and gate all dependent APIs on its success.","Check Load's return value and log the resource path on failure.","Start worker threads/callbacks only after initialization completes."],"tags":["initialization","launch","archive","startup-order","resource-pack"],"backgroundTag":"component-not-initialized","analyzedSha":"7fadd420c2351d0ffa8cac403421c1a3ed733365","analyzedAt":"2026-08-28T15:44:01.850Z","schemaVersion":2},"datasetVersion":"2026-08-28T16:17:29.566Z"}