deepinsight/insightface · critical · std::runtime_error

Archive not initialized

Error message

Archive not initialized

What it means

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.

Source

Thrown at cpp-package/inspireface/cpp/inspireface/runtime_module/launch.cpp:93

// Constructor implementation
Launch::Launch() : pImpl(std::make_unique<Impl>()) {}

// Destructor implementation
Launch::~Launch() = default;

std::shared_ptr<Launch> Launch::GetInstance() {
    std::lock_guard<std::mutex> lock(Impl::mutex_);
    if (!Impl::instance_) {
        Impl::instance_ = std::shared_ptr<Launch>(new Launch());
    }
    return Impl::instance_;
}

InspireArchive& Launch::getMArchive() {
    std::lock_guard<std::mutex> lock(pImpl->mutex_);
    if (!pImpl->m_archive_) {
        throw std::runtime_error("Archive not initialized");
    }
    return *(pImpl->m_archive_);
}

int32_t Launch::Load(const std::string& path) {
    std::lock_guard<std::mutex> lock(pImpl->mutex_);
#if defined(ISF_ENABLE_TENSORRT)
    int32_t support_cuda;
    auto ret = CheckCudaUsability(&support_cuda);
    if (ret != HSUCCEED) {
        INSPIRE_LOGE("An error occurred while checking CUDA device support. Please ensure that your environment supports CUDA!");
        return ret;
    }
    if (!support_cuda) {
        INSPIRE_LOGE("Your environment does not support CUDA! Please ensure that your environment supports CUDA!");
        return HERR_DEVICE_CUDA_NOT_SUPPORT;
    }
#endif

View on GitHub (pinned to 7fadd420c2)

Solutions

  1. Ensure Launch::Load(resource_path) is called and returns success before any API that touches the archive (feature extraction, landmark, etc.).
  2. 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.
  3. Verify the resource pack path is absolute or correctly resolved relative to the process CWD at runtime.
  4. Serialize initialization: perform Load once at startup and only start worker threads/callbacks that call the API after Load completes.

Example fix

// before
auto& archive = launch.getMArchive(); // throws "Archive not initialized"
launch.Load("res/inspireface.bundle");
// after
int32_t rc = launch.Load("res/inspireface.bundle");
if (rc != 0) { /* log and abort startup */ }
auto& archive = launch.getMArchive(); // safe
Defensive patterns

Strategy: validation

Validate before calling

int32_t rc = launch.Load(resource_path);
if (rc != 0) {
    // abort startup; archive is definitely not ready
}
// only after successful Load call APIs that use the archive

Try / catch

try {
    auto& archive = launch.getMArchive();
} catch (const std::runtime_error& e) {
    if (std::string(e.what()) == "Archive not initialized") {
        // initialization-order bug: call Load() first, then retry
    } else throw;
}

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of deepinsight/insightface@7fadd420c2 (2026-08-28). Data as JSON: /api/errors/23494446faafd7ea. Report an issue: GitHub.