apache/dolphinscheduler · critical · RuntimeException

Failed to get the product version description file. The file

Error message

Failed to get the product version description file. The file could not be found

What it means

SchemaUtils.getSoftVersion loads the product version description file (soft_version) from the classpath and reads it into a string. If the file cannot be found (FileNotFoundException while opening its InputStream), the tool cannot determine which SQL upgrade scripts to apply, so it logs and rethrows as a RuntimeException with this message.

Source

Thrown at dolphinscheduler-tools/src/main/java/org/apache/dolphinscheduler/tools/datasource/utils/SchemaUtils.java:116

        // If the version and schema version is the same from 0 up to the arrlength-1 element,whoever has a larger
        // arrLength has a larger version number
        return schemaVersionArr.length > versionArr.length;
    }

    /**
     * Gets the current software version number of the system
     *
     * @return current software version
     */
    public static String getSoftVersion() throws IOException {
        final ClassPathResource softVersionFile = new ClassPathResource("sql/soft_version");
        String softVersion;
        try (InputStream inputStream = softVersionFile.getInputStream()) {
            softVersion = FileUtils.readFile2Str(inputStream);
            softVersion = Strings.nullToEmpty(softVersion).replaceAll("\\s+|\r|\n", "");
        } catch (FileNotFoundException e) {
            log.error(e.getMessage(), e);
            throw new RuntimeException(
                    "Failed to get the product version description file. The file could not be found", e);
        }
        return softVersion;
    }

}

View on GitHub (pinned to 02eac45a1b)

Solutions

  1. Rebuild/re-extract the full dolphinscheduler-tools distribution so the version description resource is packaged
  2. Verify the soft-version file exists on the classpath (e.g. under the datasource schema/ directory) for your version
  3. Check the file path configuration passed to getSoftVersion and correct typos
  4. Run the upgrade tool from the distribution root per official docs, not from an IDE partial classpath
Defensive patterns

Strategy: try-catch

Validate before calling

// verify the resource exists before running the upgrade
String resource = "org/apache/dolphinscheduler/tools/datasource/schema/soft_version";
if (SchemaUtils.class.getClassLoader().getResource(resource) == null) {
    throw new IllegalStateException("soft_version resource missing from classpath: " + resource);
}

Try / catch

try {
    String softVersion = SchemaUtils.getSoftVersion(softVersionFile);
} catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().contains("version description file")) {
        log.error("soft_version resource missing; reinstall/repair the tools distribution", e);
    } else { throw e; }
}

Prevention

When it happens

Trigger: Running the datasource upgrade tool when the schema/soft_version resource is absent from the classpath — e.g. a broken/partial build of dolphinscheduler-tools, wrong working directory for a file-based lookup, or the resource was renamed/removed for the target version.

Common situations: Running the upgrade tool from an incomplete distribution (missing resources folder); building only part of the project so resources are not packaged; custom classloading that excludes the datasource resources; typo in the configured soft-version file path.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

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