{"record":{"id":"5baf6100b3ec7644","repo":"karatelabs/karate","slug":"failed-to-create-session-directory-directory","errorCode":null,"errorMessage":"Failed to create session directory: \" + directory","messagePattern":"Failed to create session directory: \" \\+ directory","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"karate-core/src/main/java/io/karatelabs/http/FileSessionStore.java","lineNumber":58,"sourceCode":" * File-based implementation of SessionStore.\n * Each session is stored as a JSON file in the configured directory.\n * Suitable for single-instance deployments where sessions must survive restarts\n * (e.g., Docker containers with volume mounts).\n */\npublic class FileSessionStore implements SessionStore {\n\n    private static final Logger logger = LoggerFactory.getLogger(FileSessionStore.class);\n\n    private final Path directory;\n    private long lastCleanup = System.currentTimeMillis();\n    private static final long CLEANUP_INTERVAL_MS = 300_000; // 5 minutes\n\n    public FileSessionStore(Path directory) {\n        this.directory = directory;\n        try {\n            Files.createDirectories(directory);\n        } catch (IOException e) {\n            throw new RuntimeException(\"Failed to create session directory: \" + directory, e);\n        }\n    }\n\n    @Override\n    public Session create(int expirySeconds) {\n        cleanupExpiredIfNeeded();\n        long now = Instant.now().getEpochSecond();\n        long expires = now + expirySeconds;\n        String id = UUID.randomUUID().toString();\n        Session session = new Session(id, new HashMap<>(), now, now, expires);\n        writeToDisk(session);\n        return session;\n    }\n\n    @Override\n    public Session get(String id) {\n        if (id == null) {\n            return null;","sourceCodeStart":40,"sourceCodeEnd":76,"githubUrl":"https://github.com/karatelabs/karate/blob/a22eb90246d958d15a47bf436693d0121ad2812d/karate-core/src/main/java/io/karatelabs/http/FileSessionStore.java#L40-L76","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the path does not point to an existing regular file; remove or rename it","Create the directory manually or ensure the parent exists and is writable by the process user","Fix the configured session directory path (env var/config) to a writable location","On containers, mount a writable volume at that path"],"exampleFix":"// before\nSessionStore store = new FileSessionStore(Path.of(\"/etc/ssl/private/sessions\"));\n// after: use a writable location\nSessionStore store = new FileSessionStore(Path.of(\"/var/lib/myapp/sessions\"));","handlingStrategy":"validation","validationCode":"Path dir = Path.of(configuredPath);\nif (Files.exists(dir) && !Files.isDirectory(dir)) throw new IllegalStateException(\"path is a file: \" + dir);\nif (!Files.isWritable(Files.exists(dir) ? dir : dir.getParent())) throw new IllegalStateException(\"not writable: \" + dir);","typeGuard":null,"tryCatchPattern":"try { store = new FileSessionStore(dir); } catch (RuntimeException e) { throw new IllegalStateException(\"configure a writable session dir\", e); }","preventionTips":["Point the session directory at a writable, dedicated path (e.g. /var/lib/app/sessions)","Ensure the path is not occupied by a regular file","Mount a writable volume when running in containers","Run the process as a user with permission on the parent directory"],"tags":["filesystem","io","session","directory"],"backgroundTag":"mkdir-permission-denied","analyzedSha":"a22eb90246d958d15a47bf436693d0121ad2812d","analyzedAt":"2026-09-12T09:01:00.220Z","contentChangedAt":"2026-09-12T09:01:00.220Z","schemaVersion":2},"datasetVersion":"2026-09-16T19:17:19.609Z"}