{"record":{"id":"1dced608fd925a3e","repo":"apache/cassandra","slug":"invalid-directory-directory","errorCode":null,"errorMessage":"Invalid directory {directory}","messagePattern":"Invalid directory (.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/service/StorageService.java","lineNumber":4546,"sourceCode":"            bulkLoadInternal(directory).get();\n        }\n        catch (Exception e)\n        {\n            throw new RuntimeException(e);\n        }\n    }\n\n    public String bulkLoadAsync(String directory)\n    {\n        return bulkLoadInternal(directory).planId.toString();\n    }\n\n    private StreamResultFuture bulkLoadInternal(String directory)\n    {\n        File dir = new File(directory);\n\n        if (!dir.exists() || !dir.isDirectory())\n            throw new IllegalArgumentException(\"Invalid directory \" + directory);\n\n        SSTableLoader.Client client = new SSTableLoader.Client()\n        {\n            private String keyspace;\n\n            public void init(String keyspace)\n            {\n                this.keyspace = keyspace;\n                try\n                {\n                    for (Map.Entry<Range<Token>, EndpointsForRange> entry : getRangeToAddressMap(keyspace).entrySet())\n                    {\n                        Range<Token> range = entry.getKey();\n                        EndpointsForRange replicas = entry.getValue();\n                        Replicas.temporaryAssertFull(replicas);\n                        for (InetAddressAndPort endpoint : replicas.endpoints())\n                            addRangeForEndpoint(range, endpoint);\n                    }","sourceCodeStart":4528,"sourceCodeEnd":4564,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/service/StorageService.java#L4528-L4564","documentation":"bulkLoadInternal(directory) is the implementation behind `nodetool refresh`/bulk load APIs. It validates that the given path exists and is a directory; otherwise it throws IllegalArgumentException. The path is resolved on the Cassandra server host, not the client machine.","triggerScenarios":"Calling `nodetool refresh <keyspace> <cf>` or StorageService.bulkLoad(path) with a path that doesn't exist on the server, or that is a file rather than a directory of SSTables.","commonSituations":"Copying SSTables to the wrong host or a path the cassandra user can't see; passing a local path from a remote nodetool client; staging files under a truncated/renamed directory; docker/container path mismatch.","solutions":["Verify the path on the node: it must exist and be a directory containing SSTable files (with -db, -TOC, etc. components)","Run nodetool refresh on the correct host where the SSTables were placed (scp first if remote)","Place SSTables under the table's upload directory or any directory the cassandra process can read","Check container volume mappings if running Cassandra in Docker - the path must be visible inside the container"],"exampleFix":"// before: client-local path passed to remote node\nnodetool refresh ks tbl /local/tmp/sstables\n// after: copy files to the server, then refresh\nscp -r /local/tmp/sstables node:/var/lib/cassandra/data/ks/tbl-upload-ks-tbl-ks-tbl/\nssh node 'nodetool refresh ks tbl'","handlingStrategy":"validation","validationCode":"File dir = new File(directory);\nif (!dir.exists() || !dir.isDirectory())\n    throw new IllegalArgumentException(\"not a server-side directory: \" + directory);","typeGuard":"boolean isBulkLoadableDir(String path) {\n    File d = new File(path);\n    return d.exists() && d.isDirectory();\n}","tryCatchPattern":"try { ss.bulkLoad(directory); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith(\"Invalid directory\")) { log.error(\"path missing on server host: {}\", directory); } throw e; }","preventionTips":["Remember bulkLoad/refresh paths resolve on the server, not the client","Stage SSTables in the table's -upload directory before refresh","Check that the cassandra OS user has read access to the directory","Verify container volume mappings when running in Docker"],"tags":["bulkload","filesystem","sstable"],"backgroundTag":"directory-not-found","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}