{"record":{"id":"873165591bc1838a","repo":"apache/dolphinscheduler","slug":"calculate-checksum-error","errorCode":null,"errorMessage":"Calculate checksum error.","messagePattern":"Calculate checksum error\\.","errorType":"exception","errorClass":"IOException","httpStatus":null,"severity":"error","filePath":"dolphinscheduler-common/src/main/java/org/apache/dolphinscheduler/common/utils/FileUtils.java","lineNumber":231,"sourceCode":"        CRC32 crc32 = new CRC32();\n        File file = new File(pathName);\n        String crcString = \"\";\n        if (file.isDirectory()) {\n            // file system interface remains the same order\n            String[] subPaths = file.list();\n            StringBuilder concatenatedCRC = new StringBuilder();\n            for (String subPath : subPaths) {\n                concatenatedCRC.append(getFileChecksum(pathName + FOLDER_SEPARATOR + subPath));\n            }\n            crcString = concatenatedCRC.toString();\n        } else {\n            try (\n                    FileInputStream fileInputStream = new FileInputStream(pathName);\n                    CheckedInputStream checkedInputStream = new CheckedInputStream(fileInputStream, crc32);) {\n                while (checkedInputStream.read() != -1) {\n                }\n            } catch (IOException e) {\n                throw new IOException(\"Calculate checksum error.\");\n            }\n            crcString = Long.toHexString(crc32.getValue());\n        }\n\n        return crcString;\n    }\n\n    public static void createFileWith755(@NonNull Path path) throws IOException {\n        final Path parent = path.getParent();\n        if (!parent.toFile().exists()) {\n            createDirectoryWithPermission(parent, PERMISSION_755);\n        }\n        if (SystemUtils.IS_OS_WINDOWS) {\n            Files.createFile(path);\n        } else {\n            Files.createFile(path);\n            Files.setPosixFilePermissions(path, PERMISSION_755);\n        }","sourceCodeStart":213,"sourceCodeEnd":249,"githubUrl":"https://github.com/apache/dolphinscheduler/blob/02eac45a1b6676e639fcbfb4be2243de5771b05d/dolphinscheduler-common/src/main/java/org/apache/dolphinscheduler/common/utils/FileUtils.java#L213-L249","documentation":"FileUtils.getFileChecksum computes a CRC32 checksum by streaming the file through a CheckedInputStream. If any IOException occurs while opening or reading the file, it re-throws as IOException(\"Calculate checksum error.\"), discarding the original cause and naming the operation generically.","triggerScenarios":"getFileChecksum is called and the FileInputStream cannot open the file (missing path, permission denied, path is a directory) or reading fails mid-stream (I/O error, file truncated concurrently), so the try-with-resources block throws IOException which is replaced by this message.","commonSituations":"Checksumming a resource path that doesn't exist on disk (resource packaged differently at runtime); file deleted/rotated between existence check and read; running as a user without read permission on the file; network-mounted file that became unavailable.","solutions":["Verify the file exists and is readable before the call: new File(pathName).canRead()","Log/print the suppressed root cause (initCause is lost here — reproduce the read manually with new FileInputStream(pathName) to get the real error)","Fix permissions or path: ensure the DolphinScheduler worker process user can read the file","Avoid reading files that may be concurrently written/deleted; copy to a temp file first if the source is volatile"],"exampleFix":"// before\nString crc = FileUtils.getFileChecksum(\"/opt/data/resource.zip\"); // 'Calculate checksum error.' masks real cause\n\n// after\nFile f = new File(\"/opt/data/resource.zip\");\nif (!f.exists() || !f.canRead()) {\n    throw new IllegalStateException(\"Cannot read file: \" + f.getAbsolutePath());\n}\nString crc = FileUtils.getFileChecksum(f.getAbsolutePath());","handlingStrategy":"validation","validationCode":"File f = new File(pathName);\nif (!f.isFile() || !f.canRead()) {\n    throw new IllegalStateException(\"Cannot compute checksum: file missing or unreadable: \" + f.getAbsolutePath());\n}","typeGuard":null,"tryCatchPattern":"try {\n    String crc = FileUtils.getFileChecksum(pathName);\n} catch (IOException e) {\n    if (\"Calculate checksum error.\".equals(e.getMessage())) {\n        log.error(\"Checksum failed for {}; check existence/permissions (cause suppressed by the library)\", pathName);\n    } else throw e;\n}","preventionTips":["Always check File.exists()/canRead()/isFile() before checksumming","Verify packaged resources actually exist on disk at runtime, not just in the source tree","Run workers as a user with read access to the resource directories","Avoid checksumming files under active write; snapshot to temp first"],"tags":["io","file","checksum","ioexception"],"backgroundTag":"file-read-failed","analyzedSha":"02eac45a1b6676e639fcbfb4be2243de5771b05d","analyzedAt":"2026-09-06T17:43:00.555Z","contentChangedAt":"2026-09-06T17:43:00.555Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}