Java Reference ยท java.lang
The IOException class
Reference for java.io.IOException: the checked exception behind file and stream failures, its common subclasses, UncheckedIOException and handling patterns.
java.io.IOException is the checked exception that signals a failed or interrupted input/output operation: a file that cannot be read, a stream that was closed, a disk that is full, a connection that dropped. Because it extends Exception but not RuntimeException, you must catch it or declare it with throws.
Almost every method that touches files, streams, readers, writers or sockets can throw it. More specific subclasses carry the reason: FileNotFoundException, EOFException, UncheckedIOException (a runtime wrapper), java.nio.file.NoSuchFileException, AccessDeniedException and many others.
public class IOException extends Exception
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.
Syntax
public IOException() public IOException(String message) public IOException(String message, Throwable cause) public IOException(Throwable cause)
| Constructor | Description |
|---|---|
() |
No message. |
(String message) |
A description of the failure. |
(String message, Throwable cause) |
Message and underlying cause. |
(Throwable cause) |
Wraps a cause; message becomes cause.toString(). |
Frequently met subclasses:
| Class | Typical cause |
|---|---|
FileNotFoundException |
FileInputStream, FileReader or PrintWriter on a path that cannot be opened. |
NoSuchFileException |
A java.nio.file.Files method on a missing path. |
EOFException |
A DataInput method reaches the end of the stream mid-value. |
AccessDeniedException |
Missing permissions (NIO). |
UncheckedIOException |
Unchecked wrapper (a RuntimeException) for use inside lambdas. |
SocketTimeoutException, ConnectException |
Network problems. |
Usage notes
- Catch the specific subclass first, then
IOException. Order matters: catching the superclass first is a compile error for the later, unreachable clause. - The old
java.ioclasses often throw plainFileNotFoundExceptionand give vague messages; the NIO.2FilesAPI throws more precise subclasses and includes the path in the message. - Always close resources with try-with-resources. An exception thrown by
close()while another exception is propagating is attached withaddSuppressedand read viagetSuppressed(). - Lambdas cannot throw checked exceptions from standard functional interfaces. Wrap with
UncheckedIOExceptionand unwrap withgetCause()outside, as in the example. Streams fromFiles.lines()andFiles.list()throw it from terminal operations for the same reason. - Do not swallow it. An empty
catch (IOException e) {}hides data loss. Log with the cause, retry, or propagate; wrap in a domain exception at layer boundaries. - Message content is not an API. Test the exception type, not the text; on top of that, messages differ by platform and may contain paths.
- Use
throws IOExceptiononmainin small programs and examples; in applications, translate it into something the caller can act on.