Introduction
Java does not have a standard DiskFullException or NotEnoughDiskSpaceException. When a write fails because the target storage is full, you typically see an IOException and sometimes a more specific subtype such as FileSystemException, but there is no single portable exception class you can match with instanceof.
So the real answer is best-effort detection. Catch IOException, look for file-system-specific detail when available, and treat any disk-full classification as platform-dependent rather than guaranteed by the Java API.
What Java Actually Exposes
At the API level, disk exhaustion is usually surfaced as one of these:
FileSystemException is often the most useful standard subtype because it can carry a reason string.
1import java.io.IOException;
2import java.nio.file.FileSystemException;
3
4static void inspect(IOException ex) {
5 System.out.println(ex.getClass().getName());
6 if (ex instanceof FileSystemException fse) {
7 System.out.println("reason: " + fse.getReason());
8 }
9 System.out.println("message: " + ex.getMessage());
10}
That reason text is not a stable enum. It is usually OS- and provider-specific.
A Practical Detection Helper
In application code, a helper that checks FileSystemException.getReason() first and falls back to the message is often the best you can do portably.
1import java.io.IOException;
2import java.nio.file.FileSystemException;
3import java.util.Locale;
4
5public class DiskSpaceDetector {
6 public static boolean isDiskFull(IOException ex) {
7 if (ex instanceof FileSystemException fse) {
8 String reason = fse.getReason();
9 if (matchesDiskFullText(reason)) {
10 return true;
11 }
12 }
13
14 return matchesDiskFullText(ex.getMessage());
15 }
16
17 private static boolean matchesDiskFullText(String text) {
18 if (text == null) {
19 return false;
20 }
21
22 String normalized = text.toLowerCase(Locale.ROOT);
23 return normalized.contains("no space left on device")
24|| normalized.contains("disk full") || normalized.contains("not enough space"); } } ``` This is not mathematically perfect, but it is realistic. If your code runs on a known platform set, tailor the phrases to the actual messages you observe there. ## Use It Around Writes, Not Everywhere The check only makes sense where a write or allocation failure could reasonably be caused by storage exhaustion. ```java import java.io.IOException; import java.nio.charset.StandardCharsets; import java.nio.file.Files; import java.nio.file.Path; import java.nio.file.StandardOpenOption; public class Main { public static void main(String[] args) { Path path = Path.of("output.txt"); byte[] data = "example".getBytes(StandardCharsets.UTF_8); try { Files.write(path, data, StandardOpenOption.CREATE, StandardOpenOption.APPEND); } catch (IOException ex) { if (DiskSpaceDetector.isDiskFull(ex)) { System.out.println("Write failed because storage is full."); } else { System.out.println("Write failed for another reason: " + ex.getMessage()); } } } } ``` Checking every `IOException` in a codebase for disk-full semantics is too broad. Context matters. ## Preflight Space Checks Help, But They Do Not Prove Safety You can check free space before starting a large write with `FileStore.getUsableSpace()`. ```java import java.io.IOException; import java.nio.file.FileStore; import java.nio.file.Files; import java.nio.file.Path; Path path = Path.of("."); FileStore store = Files.getFileStore(path); System.out.println(store.getUsableSpace()); ``` That is useful for warnings, admission control, or choosing an alternate destination. It does not replace exception handling. Another process can consume the remaining space immediately after your preflight check succeeds. A good pattern is: - preflight for planning - exception handling for truth ## Why There Is No Perfect Portable Check The Java standard library intentionally abstracts over many file-system details. The downside is that low-level OS error codes are not always exposed in a portable way. If your application absolutely must distinguish disk-full from every other I/O failure with high confidence, you may need: - platform-specific integration - provider-specific libraries - extensive environment testing For ordinary application code, message and reason matching is usually acceptable as long as you document it as best effort. ## Common Pitfalls The biggest mistake is assuming every write-related `IOException` means the disk is full. Permission problems, locked files, disconnected network shares, and quota issues can all show up as I/O failures. Another mistake is relying only on `getUsableSpace()` and skipping real exception handling. Developers also sometimes treat message parsing as a contractual API, when it is only a fallback strategy. If you depend on this distinction operationally, test it on the exact operating systems and file systems you deploy to. ## Summary - Java does not provide a standard disk-full exception type. - Catch `IOException` and prefer `FileSystemException` details when available. - Detect disk-full conditions with best-effort reason or message matching. - Use free-space checks only as advisory preflight logic. - If the distinction is critical, verify behavior on your real target platforms.
