apache/iceberg · error · RuntimeException

============================================================

Error message

==================================================================================
API/ABI breaks detected.
Adding RevAPI breaks should only be done after going through a deprecation cycle.
Please make sure to follow the deprecation rules defined in
https://github.com/apache/iceberg/blob/main/CONTRIBUTING.md#semantic-versioning.
==================================================================================

What it means

When RevAPI detects API/ABI breaks, this task rethrows a RuntimeException with a detailed banner pointing to the project's semantic-versioning deprecation rules. RevAPI failures must be addressed via deprecation cycles or explicit break file updates.

Source

Thrown at build.gradle:150

subprojects {
  if (it.name == 'iceberg-bom') {
    // the BOM does not build anything, the code below expects "source code"
    return
  }

  apply plugin: 'java-library'

  if (project.name in REVAPI_PROJECTS) {
    apply plugin: 'org.revapi.revapi-gradle-plugin'
    revapi {
      oldGroup = project.group
      oldName = project.name
      oldVersion = "1.11.0"
    }

    tasks.register('showDeprecationRulesOnRevApiFailure') {
      doLast {
        throw new RuntimeException("==================================================================================" +
                "\nAPI/ABI breaks detected.\n" +
                "Adding RevAPI breaks should only be done after going through a deprecation cycle." +
                "\nPlease make sure to follow the deprecation rules defined in\n" +
                "https://github.com/apache/iceberg/blob/main/CONTRIBUTING.md#semantic-versioning.\n" +
                "==================================================================================")
      }
      onlyIf {
        tasks.revapi.state.failure != null
      }
    }

    tasks.configureEach { rootTask ->
      if (rootTask.name == 'revapi') {
        rootTask.finalizedBy showDeprecationRulesOnRevApiFailure
      }
    }
    
    tasks.named("revapiAnalyze").configure {

View on GitHub (pinned to 86d9c8fc54)

Solutions

1. Revert the breaking change or make it non-breaking (add a default method, keep old overload)
2. Deprecate the old API first and stage removal for a later major version
3. If the break is intentional and approved, update the revapi break/filter configuration with justification
4. Run ./gradlew revApiCheck locally before pushing

Example fix

// before: removing a public method directly
// after
deprecated void oldMethod() { }
void newMethod() { ... }

./gradlew revApiCheck --continue  # run before every push touching public APIs

When it happens

Trigger: Running revApiCheck (or build with revapi enabled) after changing a public API in a module with revapi baseline checks, without updating the revapi breaks file.

Common situations: Renaming or removing public methods, changing method signatures, adding abstract interface methods without defaults in modules covered by revapi.

Understand the failure class

Background: "is deprecated and will be removed" — deprecation warnings for old API names, keywords, and options, and how to migrate before the removal release — this error's family across 29 libraries.

Related errors

• This build must be run with JDK 17 or 21 but was executed wi
• Neither version.txt nor git version exists:
• WARNING: Missing ${depsFile.name} in ${projectDir}. Run: ./g

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/8a36cf65adbc0a2a. Report an issue: GitHub.