karatelabs/karate · error · RuntimeException

Failed to create session directory: " + directory

Error message

Failed to create session directory: " + directory

What it means

The FileSessionStore constructor calls Files.createDirectories(directory) and wraps any IOException in a RuntimeException 'Failed to create session directory: <path>'. This fails fast when the directory for persisting HTTP sessions cannot be created.

Solutions

1. Check the path does not point to an existing regular file; remove or rename it
2. Create the directory manually or ensure the parent exists and is writable by the process user
3. Fix the configured session directory path (env var/config) to a writable location
4. On containers, mount a writable volume at that path

Example fix

// before
SessionStore store = new FileSessionStore(Path.of("/etc/ssl/private/sessions"));
// after: use a writable location
SessionStore store = new FileSessionStore(Path.of("/var/lib/myapp/sessions"));

Path dir = Path.of(configuredPath);
if (Files.exists(dir) && !Files.isDirectory(dir)) throw new IllegalStateException("path is a file: " + dir);
if (!Files.isWritable(Files.exists(dir) ? dir : dir.getParent())) throw new IllegalStateException("not writable: " + dir);

try { store = new FileSessionStore(dir); } catch (RuntimeException e) { throw new IllegalStateException("configure a writable session dir", e); }

When it happens

Trigger: Constructing new FileSessionStore(path) where the parent directory does not exist and cannot be created, the path exists as a regular file, or the process lacks write permission on the parent.

Common situations: Read-only filesystems/containers, pointing the store at a path already occupied by a file, running the app as a non-root user without permission to the configured directory, misconfigured path property.

Understand the failure class

Background: mkdir permission denied (EACCES): failed to create directory errors explained — this error's family across 32 libraries.

Related errors

• Failed to backup existing dir
• Failed to externalize embeds
• Failed to read bytes from
• ext ' ': resource vanished after validation
• ext ' ': failed reading

AI-assisted analysis of karatelabs/karate@a22eb90246 (2026-09-12). Data as JSON: /api/errors/5baf6100b3ec7644. Report an issue: GitHub.

Appendix: source

Thrown at karate-core/src/main/java/io/karatelabs/http/FileSessionStore.java:58

 * File-based implementation of SessionStore.
 * Each session is stored as a JSON file in the configured directory.
 * Suitable for single-instance deployments where sessions must survive restarts
 * (e.g., Docker containers with volume mounts).
 */
public class FileSessionStore implements SessionStore {

    private static final Logger logger = LoggerFactory.getLogger(FileSessionStore.class);

    private final Path directory;
    private long lastCleanup = System.currentTimeMillis();
    private static final long CLEANUP_INTERVAL_MS = 300_000; // 5 minutes

    public FileSessionStore(Path directory) {
        this.directory = directory;
        try {
            Files.createDirectories(directory);
        } catch (IOException e) {
            throw new RuntimeException("Failed to create session directory: " + directory, e);
        }
    }

    @Override
    public Session create(int expirySeconds) {
        cleanupExpiredIfNeeded();
        long now = Instant.now().getEpochSecond();
        long expires = now + expirySeconds;
        String id = UUID.randomUUID().toString();
        Session session = new Session(id, new HashMap<>(), now, now, expires);
        writeToDisk(session);
        return session;
    }

    @Override
    public Session get(String id) {
        if (id == null) {
            return null;

View on GitHub (pinned to a22eb90246)