apache/maven · error · IllegalArgumentException

unknown repository checksum policy: {artifactRepositoryPolic

Error message

unknown repository checksum policy: {artifactRepositoryPolicy}

What it means

ArtifactDescriptorUtils.toRepositoryChecksumPolicy maps a legacy Maven repository checksum policy string onto Resolver's policy vocabulary. Only fail, ignore and warn are accepted; any other value (failure, exception, a typo, or an unexpected string) throws IllegalArgumentException naming the offending policy.

Source

Thrown at compat/maven-resolver-provider/src/main/java/org/apache/maven/repository/internal/ArtifactDescriptorUtils.java:90

            enabled = policy.isEnabled();
            if (policy.getUpdatePolicy() != null) {
                updates = policy.getUpdatePolicy();
            }
            if (policy.getChecksumPolicy() != null) {
                checksums = policy.getChecksumPolicy();
            }
        }

        return new RepositoryPolicy(enabled, updates, checksums);
    }

    public static String toRepositoryChecksumPolicy(final String artifactRepositoryPolicy) {
        return switch (artifactRepositoryPolicy) {
            case RepositoryPolicy.CHECKSUM_POLICY_FAIL -> RepositoryPolicy.CHECKSUM_POLICY_FAIL;
            case RepositoryPolicy.CHECKSUM_POLICY_IGNORE -> RepositoryPolicy.CHECKSUM_POLICY_IGNORE;
            case RepositoryPolicy.CHECKSUM_POLICY_WARN -> RepositoryPolicy.CHECKSUM_POLICY_WARN;
            default ->
                throw new IllegalArgumentException("unknown repository checksum policy: " + artifactRepositoryPolicy);
        };
    }
}

View on GitHub (pinned to e4093d4e12)

Solutions

1. Set the checksum policy to one of fail, warn or ignore (e.g. <checksumPolicy>fail</checksumPolicy> instead of failure)
2. When reading legacy configs, normalize known legacy values before calling the converter
3. Null-check policy strings coming from optional XML elements before conversion
4. Validate policy values at configuration load time with a clear error instead of deep in resolution

Example fix

<!-- before: invalid policy string -->
<checksumPolicy>failure</checksumPolicy>

<!-- after: one of fail | warn | ignore -->
<checksumPolicy>fail</checksumPolicy>

private static final Set<String> VALID_CHECKSUM_POLICIES = Set.of("fail", "warn", "ignore");

String policy = artifactRepositoryPolicy == null
        ? "warn"
        : artifactRepositoryPolicy.toLowerCase(Locale.ROOT);
if (!VALID_CHECKSUM_POLICIES.contains(policy)) {
    throw new IllegalArgumentException("checksumPolicy must be one of " + VALID_CHECKSUM_POLICIES);
}
String resolverPolicy = ArtifactDescriptorUtils.toRepositoryChecksumPolicy(policy);

static boolean isValidChecksumPolicy(String p) {
    return p != null && Set.of("fail", "warn", "ignore").contains(p);
}

When it happens

Trigger: Converting an org.apache.maven.artifact.repository.ArtifactRepository policy whose checksum policy string is outside {fail, ignore, warn}, e.g. a legacy 'exception' value or a settings.xml typo reaching this converter during repository translation.

Common situations: <checksumPolicy> typos in settings.xml mirrors or repository definitions; legacy configurations predating policy normalization; programmatic artifact-repository construction with unchecked strings.

Related errors

• The type cannot be empty.
• The groupId cannot be empty.
• Error updating group repository metadata
• Unable to store local copy of metadata: {}
• Unable to lookup org.eclipse.aether.RepositorySystem

AI-assisted analysis of apache/maven@e4093d4e12 (2026-08-21). Data as JSON: /api/errors/7b52fd87afc27738. Report an issue: GitHub.