Skip to content
Tutorials Center
My learning

Topics

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.

Java
public class IOException extends Exception

Try it

Java Catching specific subclasses first

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.

Java Try-with-resources, suppressed exceptions and UncheckedIOException

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

Java
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.io classes often throw plain FileNotFoundException and give vague messages; the NIO.2 Files API 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 with addSuppressed and read via getSuppressed().
  • Lambdas cannot throw checked exceptions from standard functional interfaces. Wrap with UncheckedIOException and unwrap with getCause() outside, as in the example. Streams from Files.lines() and Files.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 IOException on main in small programs and examples; in applications, translate it into something the caller can act on.