ErrLookup › Background articles › IOException in Java and C#: why libraries throw the generic I/O exception for everything from missing HID devices to "Unexpected code" HTTP responses

IOException in Java and C#: why libraries throw the generic I/O exception for everything from missing HID devices to "Unexpected code" HTTP responses

IOException is the checked-exception class Java (and the equivalent System.IO exception in C#) defines for failed or interrupted I/O, but in practice open-source libraries throw it for almost anything: a device that is not connected, a non-2xx HTTP status, a truncated binary file, an idle replication socket, a missing config key, even a dead child process. If you landed on this error, the message text and the wrapped cause matter far more than the class name, because the same IOException surfaces from hardware, network, filesystem, parser, and configuration layers depending on the library.

Distilled from 754 documented records across 54 repositories.

Background

At the platform layer, IOException signals that an input or output operation failed or was interrupted: java.io.IOException is a checked exception that callers must catch or declare, and .NET's System.IO.IOException plays the same role for Windows-era I/O errors. That checked nature is exactly why libraries reach for it outside raw I/O. When an API's signature already declares "throws IOException" — an HTTP client call, a demuxer read, a file-system committer — the cheapest way to abort with an application-level failure is to throw an IOException with a descriptive message, because every caller already handles it. OkHttp's recipes do this explicitly ("Unexpected code " + response turns a non-2xx status into a checked exception the recipe is allowed to throw), and Spring Cloud Alibaba aborts startup over a missing schedulerx appKey the same way.

A second pattern in this family is masking: the IOException you catch is often a wrapper around a more precise exception that the library caught and rethrew. G-Helper's WindowsUsbProvider catches the InvalidOperationException from LINQ's .First() when no HID device matches and rethrows it as an IOException with only the device name in the message; Hutool wraps its length-mismatch IOException inside IORuntimeException; opendataloader-pdf wraps any worker-thread failure in a bare "Parallel page processing failed" IOException with the real cause hidden in getCause(). The caller sees IOException; the diagnosis lives one or two levels down the cause chain.

The family also varies enormously by layer. Within these 54 repositories the same class covers: absent hardware (ASUS HID devices not enumerated, Steam registry keys missing), external-service failures (OpenAI Responses API returning 429, the retired Google URL Shortener returning 403), corrupt or truncated binary structures (jadx chunk-magic mismatches in resources.arsc, negative block sizes in NewPipe's WebM parser, MySQL binlog status-var underflow in Canal), stalled or dropped connections (Canal's 10ms-tick read timeout, its netty channel registration race), filesystem races (Hutool's TOCTOU length check, Flink committers finding the temp file gone), and even control flow and security guards (Flink throwing "operation interrupted" after restoring an interrupt flag, Ghidra rejecting zip-slip archive names, OkHttp's recipe denylisting a pinned certificate). Some of these are retryable, some signal corruption, and some are deliberate programming-error assertions, so the message — not the class — is the only reliable discriminator.

From the caller's side, an IOException therefore tells you where in the code the failure was noticed, not what went wrong. The records repeatedly show the same diagnostic move: read the formatted values in the message (expected vs actual checksums, HTTP status codes, requested vs buffered byte counts), then inspect the cause or inner exception, then decide whether the underlying condition is absence, corruption, concurrency, or expiry before choosing a fix.

Common causes

What usually fixes it

Go deeper

Documented occurrences

…and 734 more across the corpus — use search.

Honest provenance: generated on 2026-08-14 from AI-assisted analysis of the linked records. See how records are made.