What causes "Unknown storage mode: " + mode" in floci-io/floci?

Set the mode to one of: memory, persistent, hybrid, wal

floci-io/floci · critical · IllegalArgumentException

Unknown storage mode: " + mode

Error message

Unknown storage mode: " + mode

What it means

Thrown by StorageFactory when creating a storage backend with a mode string that is not one of memory, persistent, hybrid, or wal (switch default branch). The mode comes from floci.storage configuration, globally or per-service, so this is a config typo caught lazily at first backend creation for that path.

Source

Thrown at src/main/java/io/github/hectorvent/floci/core/storage/StorageFactory.java:93

        LOG.debugv("Creating {0} storage for service {1} (file: {2})", mode, serviceName, filePath);

        StorageBackend<String, V> inner = switch (mode) {
            case "memory" -> new InMemoryStorage<>();
            case "persistent" -> new PersistentStorage<>(filePath, typeReference);
            case "hybrid" -> {
                var hybrid = new HybridStorage<>(filePath, typeReference, flushInterval);
                hybridBackends.add(hybrid);
                yield hybrid;
            }
            case "wal" -> {
                Path snapshotPath = basePath.resolve(fileName.replace(".json", "-snapshot.json"));
                Path walFilePath = basePath.resolve(fileName.replace(".json", ".wal"));
                long compactionInterval = config.storage().wal().compactionIntervalMs();
                var wal = new WalStorage<>(snapshotPath, walFilePath, typeReference, compactionInterval);
                walBackends.add(wal);
                yield wal;
            }
            default -> throw new IllegalArgumentException("Unknown storage mode: " + mode);
        };

        inner.load();

        AccountAwareStorageBackend<V> backend = new AccountAwareStorageBackend<>(
                inner, requestContextInstance, config.defaultAccountId());
        allBackends.add(backend);
        backendsByPath.put(filePath, backend);
        return backend;
    }

    /** Load all storage backends from disk. */
    public synchronized void loadAll() {
        for (StorageBackend<?, ?> backend : allBackends) {
            backend.load();
        }
    }

View on GitHub (pinned to 62ff490619)

Solutions

Set the mode to one of: memory, persistent, hybrid, wal
Check both the global floci.storage.mode and any per-service overrides for typos and casing
Search config for the exact bad value shown in the message

Example fix

# before
floci.storage.mode: persistant

# after
floci.storage.mode: persistent

Defensive patterns

Strategy: type-guard

Validate before calling

static final Set<String> VALID_MODES = Set.of("memory", "persistent", "hybrid", "wal");
boolean validMode(String mode) { return VALID_MODES.contains(mode); }

Type guard

boolean isStorageMode(Object m) {
    return m instanceof String s && Set.of("memory", "persistent", "hybrid", "wal").contains(s);
}

Try / catch

try {
    storageFactory.create(path, typeRef);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Unknown storage mode")) { correctModeConfig(); } // config typo, fix and restart
}

Prevention

Validate storage mode strings at config load time, not at first backend creation
Use enum-backed config binding where available so invalid values fail fast at parse time
Copy mode names exactly from docs: lower-case

When it happens

Trigger: Setting floci.storage.mode (or a per-service storage mode, or FLOCI_STORAGE_MODE) to a misspelled value like 'persistant', 'Memory', 'file', 'local', or 'wla'. The error fires when the affected service first asks StorageFactory for a backend.

Common situations: Typos in YAML/env config; carrying config from another emulator's naming conventions (e.g. 'file' or 'disk'); case sensitivity; upgrading floci versions where mode names changed.

Related errors

AI-assisted analysis of floci-io/floci@62ff490619 (2026-08-14). Data as JSON: /api/errors/9654139abce81ecf. Report an issue: GitHub.