{"record":{"id":"ff236a34d02f0a8b","repo":"oracle/graal","slug":"error-setting-up-directio","errorCode":null,"errorMessage":"Error setting up DirectIO","messagePattern":"Error setting up DirectIO","errorType":"exception","errorClass":"UnsupportedOperationException","httpStatus":null,"severity":"error","filePath":"espresso/src/com.oracle.truffle.espresso.io/src/sun/nio/ch/FileDispatcherImpl.java","lineNumber":102,"sourceCode":"    }\n\n    @Override\n    boolean transferToDirectlyNeedsPositionLock() {\n        return false;\n    }\n\n    @Override\n    boolean canTransferToFromOverlappedMap() {\n        return false;\n    }\n\n    @Override\n    int setDirectIO(FileDescriptor fd, String path) {\n        int result = -1;\n        try {\n            result = setDirect0(fd, path);\n        } catch (IOException e) {\n            throw new UnsupportedOperationException(\"Error setting up DirectIO\", e);\n        }\n        return result;\n    }\n\n    @Override\n    int read(FileDescriptor fd, long address, int len) throws IOException {\n        return truffleDispatcher.read(fd, address, len);\n    }\n\n    @Override\n    long readv(FileDescriptor fd, long address, int len) throws IOException {\n        return truffleDispatcher.readv(fd, address, len);\n    }\n\n    @Override\n    int write(FileDescriptor fd, long address, int len) throws IOException {\n        return truffleDispatcher.write(fd, address, len);\n    }","sourceCodeStart":84,"sourceCodeEnd":120,"githubUrl":"https://github.com/oracle/graal/blob/a66e9ccd1d7bf2552883939aa0788dfd0e294aab/espresso/src/com.oracle.truffle.espresso.io/src/sun/nio/ch/FileDispatcherImpl.java#L84-L120","documentation":"This sun.nio.ch.FileDispatcherImpl substitution maps setDirectIO onto a native call; when the native setDirect0 throws IOException (filesystem does not support O_DIRECT, invalid alignment, etc.), it is wrapped in UnsupportedOperationException('Error setting up DirectIO'). Guest code using DirectByteBuffer/FileChannel with DIRECT I/O on unsupported storage gets this instead of the raw IOException.","triggerScenarios":"Guest Java code opening a FileChannel with ExtendedOpenOption.DIRECT and the underlying FS (e.g. tmpfs, network FS, or a file on overlayfs in containers) rejecting O_DIRECT; alignment requirements not met by buffer/address.","commonSituations":"Databases and storage engines (RocksDB-style code paths) enabling DIRECT I/O inside containers/overlay filesystems or on macOS/tmpfs where O_DIRECT is unsupported.","solutions":["Fall back to non-direct I/O: open the channel without ExtendedOpenOption.DIRECT when UnsupportedOperationException is thrown.","Run the workload on a filesystem supporting O_DIRECT (ext4/xfs on a real block device, not tmpfs/overlay).","Ensure buffer and file offsets are aligned to the filesystem's block size if DIRECT must be used."],"exampleFix":"// before\nFileChannel ch = FileChannel.open(p, StandardOpenOption.READ, ExtendedOpenOption.DIRECT); // throws on tmpfs\n\n// after\nFileChannel ch;\ntry {\n    ch = FileChannel.open(p, StandardOpenOption.READ, ExtendedOpenOption.DIRECT);\n} catch (UnsupportedOperationException e) {\n    ch = FileChannel.open(p, StandardOpenOption.READ); // buffered fallback\n}","handlingStrategy":"fallback","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    ch = FileChannel.open(p, READ, ExtendedOpenOption.DIRECT);\n} catch (UnsupportedOperationException e) {\n    if (e.getMessage().equals(\"Error setting up DirectIO\")) {\n        ch = FileChannel.open(p, READ); // fallback to buffered I/O\n    } else throw e;\n}","preventionTips":["Probe DIRECT support once at startup and cache the decision.","Avoid O_DIRECT on tmpfs/overlay/network filesystems and in containers."],"tags":["espresso","nio","direct-io","filesystem"],"backgroundTag":null,"analyzedSha":"a66e9ccd1d7bf2552883939aa0788dfd0e294aab","analyzedAt":"2026-08-14T13:58:47.161Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}