apache/dolphinscheduler · error · IOException

Calculate checksum error.

Error message

Calculate checksum error.

What it means

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.

Source

Thrown at dolphinscheduler-common/src/main/java/org/apache/dolphinscheduler/common/utils/FileUtils.java:231

        CRC32 crc32 = new CRC32();
        File file = new File(pathName);
        String crcString = "";
        if (file.isDirectory()) {
            // file system interface remains the same order
            String[] subPaths = file.list();
            StringBuilder concatenatedCRC = new StringBuilder();
            for (String subPath : subPaths) {
                concatenatedCRC.append(getFileChecksum(pathName + FOLDER_SEPARATOR + subPath));
            }
            crcString = concatenatedCRC.toString();
        } else {
            try (
                    FileInputStream fileInputStream = new FileInputStream(pathName);
                    CheckedInputStream checkedInputStream = new CheckedInputStream(fileInputStream, crc32);) {
                while (checkedInputStream.read() != -1) {
                }
            } catch (IOException e) {
                throw new IOException("Calculate checksum error.");
            }
            crcString = Long.toHexString(crc32.getValue());
        }

        return crcString;
    }

    public static void createFileWith755(@NonNull Path path) throws IOException {
        final Path parent = path.getParent();
        if (!parent.toFile().exists()) {
            createDirectoryWithPermission(parent, PERMISSION_755);
        }
        if (SystemUtils.IS_OS_WINDOWS) {
            Files.createFile(path);
        } else {
            Files.createFile(path);
            Files.setPosixFilePermissions(path, PERMISSION_755);
        }

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Verify the file exists and is readable before the call: new File(pathName).canRead()
2. Log/print the suppressed root cause (initCause is lost here — reproduce the read manually with new FileInputStream(pathName) to get the real error)
3. Fix permissions or path: ensure the DolphinScheduler worker process user can read the file
4. Avoid reading files that may be concurrently written/deleted; copy to a temp file first if the source is volatile

Example fix

// before
String crc = FileUtils.getFileChecksum("/opt/data/resource.zip"); // 'Calculate checksum error.' masks real cause

// after
File f = new File("/opt/data/resource.zip");
if (!f.exists() || !f.canRead()) {
    throw new IllegalStateException("Cannot read file: " + f.getAbsolutePath());
}
String crc = FileUtils.getFileChecksum(f.getAbsolutePath());

File f = new File(pathName);
if (!f.isFile() || !f.canRead()) {
    throw new IllegalStateException("Cannot compute checksum: file missing or unreadable: " + f.getAbsolutePath());
}

try {
    String crc = FileUtils.getFileChecksum(pathName);
} catch (IOException e) {
    if ("Calculate checksum error.".equals(e.getMessage())) {
        log.error("Checksum failed for {}; check existence/permissions (cause suppressed by the library)", pathName);
    } else throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

• Create xlsx directory error
• generate excel error
• Update the resource file from content: {fileAbsolutePath} fa
• Download the resource file: {fileAbsolutePath} failed
• The path is not a file: ${fileAbsolutePath}

AI-assisted analysis of apache/dolphinscheduler@02eac45a1b (2026-09-06). Data as JSON: /api/errors/873165591bc1838a. Report an issue: GitHub.