apache/dolphinscheduler · error · RuntimeException

schemaVersion or version is empty

Error message

schemaVersion or version is empty

What it means

SchemaUtils.isAGreatVersion validates that both version strings are non-empty before comparing them component-wise. If either the schema version (from version metadata) or the target version string is null/empty, it throws this RuntimeException instead of comparing. It is a guard against corrupted or missing version information during upgrade checks.

Source

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

                return -1;
            } catch (Exception e) {
                log.error(e.getMessage(), e);
                throw new RuntimeException(e);
            }
        }).collect(Collectors.toList());
    }

    /**
     * Determine whether schemaVersion is higher than version
     *
     * @param schemaVersion schema version
     * @param version version
     * @return Determine whether schemaVersion is higher than version
     */
    public static boolean isAGreatVersion(String schemaVersion, String version) {
        if (Strings.isNullOrEmpty(schemaVersion) || Strings.isNullOrEmpty(version)) {
            throw new RuntimeException("schemaVersion or version is empty");
        }

        String[] schemaVersionArr = schemaVersion.split("\\.");
        String[] versionArr = version.split("\\.");
        int arrLength = Math.min(schemaVersionArr.length, versionArr.length);
        for (int i = 0; i < arrLength; i++) {
            if (Integer.parseInt(schemaVersionArr[i]) > Integer.parseInt(versionArr[i])) {
                return true;
            } else if (Integer.parseInt(schemaVersionArr[i]) < Integer.parseInt(versionArr[i])) {
                return false;
            }
        }

        // 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;
    }

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Verify the version info in the metadata DB (schema_version) is populated
2. Ensure the caller passes the correct, non-empty target version string
3. Restore correct version metadata from a backup before re-running the upgrade tool
4. Add a pre-check that validates version strings before invoking SchemaUtils

Example fix

// before
SchemaUtils.isAGreatVersion(currentVersion, null);
// after
if (Strings.isNullOrEmpty(currentVersion) || Strings.isNullOrEmpty(targetVersion)) {
    throw new IllegalStateException("version metadata missing: current=" + currentVersion + ", target=" + targetVersion);
}
boolean greater = SchemaUtils.isAGreatVersion(currentVersion, targetVersion);

import org.apache.hbase.thirdparty.com.google.common.base.Strings; // or guava
if (Strings.isNullOrEmpty(schemaVersion) || Strings.isNullOrEmpty(targetVersion)) {
    throw new IllegalStateException("Version metadata incomplete: schemaVersion=" + schemaVersion + ", version=" + targetVersion);
}
SchemaUtils.isAGreatVersion(schemaVersion, targetVersion);

private static boolean hasVersion(String v) {
    return v != null && !v.trim().isEmpty();
}

try {
    boolean greater = SchemaUtils.isAGreatVersion(schemaVersion, targetVersion);
} catch (RuntimeException e) {
    if ("schemaVersion or version is empty".equals(e.getMessage())) {
        log.error("Version metadata missing; check schema_version table and configured version", e);
    } else { throw e; }
}

When it happens

Trigger: Calling isAGreatVersion(schemaVersion, version) with a null/empty argument, typically when the schema_version row in the metadata DB is missing/empty or a version string constant was not resolved.

Common situations: Upgrading a DB whose version table was never populated or was truncated; passing an unconfigured/unresolved version variable; manually editing version metadata.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• url can not be null
• 10001
• namespace %s does not exist in k8s cluster, please create na
• ID token is missing required claims
• REQUEST_PARAMS_NOT_VALID_ERROR

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