apache/cassandra · error · IllegalArgumentException

Unknown IOMode

Error message

Unknown IOMode 

What it means

Thrown by ChannelProxy.openOptions when a file read mode other than DIRECT or BUFFERED is passed. ioMode must be one of the known IOMode enum values that map to a set of OpenOptions used to open the read channel.

Solutions

1. Set disk_access_mode to a valid value (auto, mmap, standard/direct) in cassandra.yaml
2. Check the ioMode value passed to the ChannelProxy constructor in custom code and use only IOMode.DIRECT or IOMode.BUFFERED
3. Upgrade/patch the mapping code so every IOMode enum variant has a case
4. Validate configuration values at startup before file access

Example fix

// before
ChannelProxy p = new ChannelProxy(file, ioMode /* null/unknown */);
// after
ChannelProxy p = new ChannelProxy(file, ioMode == null ? IOMode.BUFFERED : ioMode);

// validate ioMode before constructing
if (ioMode != IOMode.DIRECT && ioMode != IOMode.BUFFERED) throw new IllegalArgumentException("ioMode must be DIRECT or BUFFERED, got " + ioMode);

static boolean isSupported(IOMode m) { return m == IOMode.DIRECT || m == IOMode.BUFFERED; }

try { ch = new ChannelProxy(path, ioMode); } catch (IllegalArgumentException e) { ch = new ChannelProxy(path, IOMode.BUFFERED); }

When it happens

Trigger: Constructing a ChannelProxy (or Config-aware file open path) with an ioMode value not in the supported set — e.g. a null/unknown Config.disk_access_mode mapping, or programmatic misuse passing a raw string/enum variant the switch doesn't handle.

Common situations: Invalid disk_access_mode in cassandra.yaml producing an unexpected IOMode, custom code constructing ChannelProxy with an unhandled mode, config parsing regressions after upgrades.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Cannot read index summary because min_index_interval…
• Corrupt value length
• failed to create encyption context for hints file. ignoring…
• Rebuilding index summary because the effective index…
• A repair_session_space of

AI-assisted analysis of apache/cassandra@88fd0f6a0e (2026-09-10). Data as JSON: /api/errors/968bb6992c063f53. Report an issue: GitHub.

Appendix: source

Thrown at src/java/org/apache/cassandra/io/util/ChannelProxy.java:78

        {
            return FileChannel.open(file.toPath(), openOptions);
        }
        catch (IOException e)
        {
            throw new RuntimeException(e);
        }
    }

    private static OpenOption[] openOptions(IOMode ioMode)
    {
        switch (ioMode)
        {
            case DIRECT:
                return new OpenOption[]{ StandardOpenOption.READ, ExtendedOpenOption.DIRECT };
            case BUFFERED:
                return new OpenOption[]{ StandardOpenOption.READ };
            default:
                throw new IllegalArgumentException("Unknown IOMode " + ioMode);
        }
    }

    public ChannelProxy(String path)
    {
        this(new File(path));
    }

    public ChannelProxy(File file)
    {
        this(file, IOMode.BUFFERED);
    }

    public ChannelProxy(File file, IOMode ioMode)
    {
        this(file, openChannel(file, openOptions(ioMode)));
    }

View on GitHub (pinned to 88fd0f6a0e)