microsoft/FASTER · error

Failed to schedule async IO: , handle

Error message

Failed to schedule async IO: , handle 

What it means

Same async-I/O scheduling failure as the preceding variant, but this class includes the underlying file handle in the diagnostic: 'Failed to schedule async IO: <win32 error>, handle <n>'. The overlapped call returned something other than ERROR_IO_PENDING, so Status::IOError is returned.

Solutions

1. Use the printed handle number to identify the failing file/device
2. Resolve the underlying Win32 error shown by FormatWin32AndHRESULT
3. Check buffer alignment and I/O quotas; verify disk health and free space
4. Retry or reopen the device if the failure persists

Example fix

null

null

Status s = op();
if (s == Status::IOError) {
  // parse handle from stderr line to identify failing device
  // reopen device or fail over to healthy storage
}

When it happens

Trigger: Queuing async I/O on a Windows thread-pool file when the overlapped request fails immediately; the message's handle number identifies which file/device failed.

Common situations: Multiple devices where only one has gone bad (handle helps pinpoint it), unaligned buffers, quota/disk exhaustion, closed or corrupted handles.

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

• Failed to schedule async IO:
• Failed to schedule work:
• Cannot use LocalStorageDevice from non-Windows OS platform…
• Path is too long
• Error reading from log file

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

Appendix: source

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

  new(io_context.get()) QueueIoHandler::IoCallbackContext(offset, caller_context_copy,
      callback);

  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) {
      std::stringstream ss;
      ss << "Failed to schedule async IO: " << FormatWin32AndHRESULT(win32_result) <<
         ", handle " << std::to_string((uint64_t)file_handle_);
      fprintf(stderr, "%s\n", ss.str().c_str());
      return Status::IOError;
    }
  }
  io_context.release();
  return Status::Ok;
}

#undef DCHECK_ALIGNMENT

}
} // namespace FASTER::environment

View on GitHub (pinned to 321d872eab)