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.
try { string text = File.ReadAllText("settings.ini"); } catch (FileNotFoundException) { // use defaults }
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 Console.ReadLine()), 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 Console.ReadLine()), it gets the next line from this box.
Syntax
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.
FileNotFoundExceptionandDirectoryNotFoundExceptionbeforeIOException, otherwise the compiler reports error CS0160. - Prefer a check for expected misses.
File.ExistsorDirectory.Existsavoids 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.CreateNeworFileMode.OpenOrCreateand 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.
usingreleases 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
IOExceptionfor broken connections;SocketExceptionis wrapped inside it forNetworkStream. - Async methods throw the same types, but the exception appears when you
awaitthe returned task.