What causes "Failed to schedule async IO: " in microsoft/FASTER?

Inspect the FormatWin32AndHRESULT output on stderr for the exact Win32 error code

Failed to schedule async IO:

Error message

Failed to schedule async IO:

What it means

ThreadPoolFile::ScheduleOperation issues overlapped (async) I/O via the Windows thread pool. If the overlapped call returns anything other than ERROR_IO_PENDING, the I/O could not be queued; CancelThreadpoolIo is called, the formatted Win32/HRESULT error is printed, and Status::IOError is returned.

Solutions

Inspect the FormatWin32AndHRESULT output on stderr for the exact Win32 error code
Ensure read/write buffers meet Windows overlapped-I/O alignment requirements
Check disk space, pagefile/quota settings and device health
Retry the operation; if persistent, reopen the device/log
Verify ERROR_IO_PENDING-style async expectations match your FASTER version

Example fix

null

Defensive patterns

Strategy: try-catch

Validate before calling

null

Try / catch

Status s = kv.Read/Write(...);
if (s == Status::IOError) {
  // read the stderr 'Failed to schedule async IO: <win32 error>'
  // fall back to sync I/O or retry with aligned buffers
}

Prevention

Use FASTER-aligned buffer pools for user I/O
Monitor disk free space and quotas
Check the Windows event log for disk faults

When it happens

Trigger: Any async read/write through a ThreadPoolFile-backed device (Windows) where the overlapped I/O call fails immediately — e.g. invalid buffer alignment, insufficient quota, handle issues, disk full.

Common situations: Unaligned user buffers passed to FASTER on Windows, disk or paging-file quota exhaustion, failing/faulty storage devices, calling I/O after the file handle was invalidated.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

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

Appendix: source

Thrown at cc/src/environment/file_windows.cc:269

      callback);

  ::StartThreadpoolIo(io_object_);

  bool success = FALSE;
  if(FileOperationType::Read == operationType) {
    success = ::ReadFile(file_handle_, buffer, length, nullptr, &io_context->parent_overlapped);
  } else {
    success = ::WriteFile(file_handle_, buffer, length, nullptr, &io_context->parent_overlapped);
  }
  if(!success) {
    DWORD win32_result = ::GetLastError();
    // Any error other than ERROR_IO_PENDING means the IO failed. Otherwise it will finish
    // asynchronously on the threadpool
    if(ERROR_IO_PENDING != win32_result) {
      ::CancelThreadpoolIo(io_object_);
      std::stringstream ss;
      ss << "Failed to schedule async IO: " << FormatWin32AndHRESULT(win32_result);
      fprintf(stderr, "%s\n", ss.str().c_str());
      return Status::IOError;
    }
  }
  io_context.release();
  return Status::Ok;
}

bool QueueIoHandler::TryComplete() {
  DWORD bytes_transferred;
  ULONG_PTR completion_key;
  LPOVERLAPPED overlapped = NULL;
  bool succeeded = ::GetQueuedCompletionStatus(io_completion_port_, &bytes_transferred,
                   &completion_key, &overlapped, 0);
  if(overlapped) {
    Status return_status;
    if(!succeeded) {
      return_status = Status::IOError;
    } else {

View on GitHub (pinned to 321d872eab)