Skip to content
Tutorials Center
My learning

Topics

C# Reference ยท Exceptions and Diagnostics

The IOException family

Reference for IOException and its subclasses in C#: FileNotFoundException, DirectoryNotFoundException, PathTooLongException, EndOfStreamException and how to handle them.

System.IO.IOException is the base class for errors that happen while working with files, directories, streams and pipes. Most of the time you meet one of its subclasses: FileNotFoundException, DirectoryNotFoundException, PathTooLongException, EndOfStreamException, FileLoadException, and InvalidDataException from the compression APIs.

Access problems are a separate branch. UnauthorizedAccessException is not an IOException: it derives from SystemException. A file that is locked by another process, a full disk or a broken network share is reported as plain IOException with an operating-system message.

C#
try
{
    string text = File.ReadAllText("settings.ini");
}
catch (FileNotFoundException)
{
    // use defaults
}

Try it

C# Which exception for which failure

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 Console.ReadLine()), it gets the next line from this box.

C# Order the catch blocks, then retry

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 Console.ReadLine()), it gets the next line from this box.

Syntax

C#
public class IOException : SystemException
{
    public IOException();
    public IOException(string? message);
    public IOException(string? message, Exception? innerException);
    public IOException(string? message, int hresult);
}

// Common subclasses in System.IO
public class FileNotFoundException : IOException
{
    public string? FileName { get; }
    public string? FusionLog { get; }
}
public class DirectoryNotFoundException : IOException { }
public class PathTooLongException : IOException { }
public class EndOfStreamException : IOException { }
public class FileLoadException : IOException { }
Type Typical cause
FileNotFoundException The file does not exist. FileName holds the path that failed.
DirectoryNotFoundException A folder in the path does not exist. Also thrown when you write into a missing folder.
PathTooLongException The path exceeds the system limit.
EndOfStreamException BinaryReader ran out of data in the middle of a value.
IOException Lock violations, sharing violations, full disks, network errors.
UnauthorizedAccessException Permission denied, or the path is a directory. Not an IOException.

Errors / undefined behavior: which exact subclass you get can differ between operating systems. Do not parse messages; check the type or HResult.

Usage notes

  • Catch the most specific type first. FileNotFoundException and DirectoryNotFoundException before IOException, otherwise the compiler reports error CS0160.
  • Prefer a check for expected misses. File.Exists or Directory.Exists avoids exceptions for normal "not there yet" cases, but another process can still change things between the check and the use. Handle the exception anyway.
  • Check-then-use is racy. For atomic behavior use FileMode.CreateNew or FileMode.OpenOrCreate and handle the exception.
  • Locks are transient. A sharing violation often succeeds on retry after a short delay; give up after a few attempts and rethrow.
  • Always dispose streams. using releases the handle even when an exception is thrown, which prevents the next open from failing with a lock error.
  • Do not show raw messages to end users. They include internal paths. Log the full exception and show a friendly text.
  • Network paths and pipes raise IOException for broken connections; SocketException is wrapped inside it for NetworkStream.
  • Async methods throw the same types, but the exception appears when you await the returned task.