What causes "Failed to open file for hybrid log" in microsoft/FASTER?

Ensure the local root directory exists and is writable by the process

microsoft/FASTER · critical · std::runtime_error

Failed to open file for hybrid log

Error message

Failed to open file for hybrid log

What it means

The StorageDevice constructor opens its hybrid log via hLog.Open(); if the returned status is not Ok, it logs 'Failed to open hybrid log file on Storage device' and throws std::runtime_error('Failed to open file for hybrid log'). Construction of the device (and therefore FASTER init) fails.

Solutions

Ensure the local root directory exists and is writable by the process
If using Azure storage, verify the emulator/account connectivity (e.g. start the storage emulator for UseDevelopmentStorage)
Catch the std::runtime_error around device construction and reinitialize with a corrected path
Check the preceding logMessage output for Open()'s failure reason

Example fix

// before
FASTER::device::StorageDevice dev("C:/does/not/exist", ...);
// after (create dir first, then guard construction)
std::filesystem::create_directories("C:/faster-data");
try {
  FASTER::device::StorageDevice dev("C:/faster-data", ...);
} catch (const std::runtime_error& e) { /* handle */ }

Defensive patterns

Strategy: try-catch

Validate before calling

if (!std::filesystem::exists(localRoot) ||
    !std::filesystem::is_directory(localRoot))
  throw std::runtime_error("hlog root missing: " + localRoot);

Try / catch

try {
  FASTER::device::StorageDevice dev(root, ...);
} catch (const std::runtime_error& e) {
  if (std::string(e.what()).find("hybrid log") != std::string::npos) {
    // fix path/permissions or storage connectivity, then retry
  }
}

Prevention

Create and permission-check the local root directory before init
For Azure storage, verify emulator/account availability pre-startup
Check hLog.Open()'s logMessage output for the root cause

When it happens

Trigger: Constructing a StorageDevice whose hLog.Open() fails — missing local root directory, bad path/permissions, Azure storage emulator ('UseDevelopmentStorage') not running, or storage connection failures.

Common situations: Pointing FASTER at a nonexistent local path, insufficient write permissions, using the development-storage constructor without the Azure storage emulator started, wrong connection settings.

Understand the failure class

Background: "open() failed", "failed to open file", "cannot create file" — what a file open error means and how to fix it — this error's family across 42 libraries.

Related errors

AI-assisted analysis of microsoft/FASTER@321d872eab (2026-09-15). Data as JSON: /api/errors/ba2ec25e4edb4e36. Report an issue: GitHub.

Appendix: source

Thrown at cc/src/device/storage.h:1101

  ///    operating system.
  /// \param deleteOnClose
  ///    If set to true, files created by the device will be deleted by the
  ///    underlying operating system once closed.
  StorageDevice(const std::string& root, LightEpoch& lEpoch,
                const std::string& remote, uint16_t id=1,
                bool unBuffered=false, bool deleteOnClose=false)
    : localRoot{ FASTER::environment::NormalizePath(root) }
    , epoch{ &lEpoch }
    , unBuffered{ unBuffered }
    , deleteOnClose{ deleteOnClose }
    , ioHandler{ 8 }
    , hLog{ localRoot, &ioHandler, &lEpoch, &pendingTasks, id, remote,
            1024, 302, 30 }
  {
    if (hLog.Open() != Status::Ok) {
      logMessage(Lvl::ERR,
                 "Failed to open hybrid log file on Storage device");
      throw std::runtime_error("Failed to open file for hybrid log");
    }
  }

  /// Constructor for unit testing.
  ///
  /// \param lEpoch
  ///    Pointer to the epoch manager.
  StorageDevice(LightEpoch& lEpoch)
    : localRoot{ "C:\\faster\\" }
    , epoch{ &lEpoch }
    , unBuffered{ false }
    , deleteOnClose{ false }
    , ioHandler{ 8 }
    , hLog{ localRoot, &ioHandler, &lEpoch, &pendingTasks, 1,
            "UseDevelopmentStorage=true;" }
  {
    if (hLog.Open() != Status::Ok) {
      logMessage(Lvl::ERR,

View on GitHub (pinned to 321d872eab)