apache/iceberg · error · NoSuchFunctionException

Cannot load function

Error message

Cannot load function: %s.%s

What it means

Thrown by SupportsFunctions.loadFunction when the requested Iceberg system function cannot be resolved through any of the registered SparkFunctions providers. Iceberg exposes catalog-level functions (e.g. system functions); when none of the function builders can produce an UnboundFunction for the given identifier, this NoSuchFunctionException signals the function does not exist in the catalog.

Solutions

  1. Check the function name and namespace for typos and verify it against the Iceberg functions supported by your version
  2. Upgrade the Iceberg Spark runtime to a version that registers the desired function
  3. If the logic exists only as a Spark builtin, do not route it through the Iceberg function catalog — call the Spark function directly

Example fix

// before
SELECT iceberg.system.mbytes(1);
// after
SELECT iceberg.system.mbytes(1048576); -- use a function that exists in the catalog
Defensive patterns

Strategy: try-catch

Validate before calling

// Verify the function exists before calling
try (Functions funcs = Functions.load()) {
  if (funcs.function(name()) == null) { /* function missing */ }
}

Type guard

boolean functionExists(String ident) { return SparkFunctions.load(ident) != null; }

Try / catch

try { return supportsFunctions.loadFunction(ident); } catch (NoSuchFunctionException e) { throw new AnalysisException("Unknown function: " + ident, e); }

Prevention

When it happens

Trigger: Calling a catalog function via Spark SQL such as SELECT iceberg.system.some_fn(...) or referencing an Iceberg function in an expression where the identifier (namespace-qualified name) does not match any function registered in SparkFunctions.

Common situations: Typo in the function name; using a function that exists in another Iceberg version but not the one on the classpath; qualifying the function with the wrong namespace; expecting engine-builtin functions to be resolvable through the Iceberg function catalog.

Understand the failure class

Background: Record Not Found Errors: "not found", RecordNotFound, and "was not found" — what they mean and how to fix them — this error's family across 28 libraries.

Related errors

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

Appendix: source

Thrown at spark/v3.5/spark/src/main/java/org/apache/iceberg/spark/SupportsFunctions.java:64

      return new Identifier[0];
    }

    throw new NoSuchNamespaceException(namespace);
  }

  @Override
  default UnboundFunction loadFunction(Identifier ident) throws NoSuchFunctionException {
    String[] namespace = ident.namespace();
    String name = ident.name();

    if (isFunctionNamespace(namespace)) {
      UnboundFunction func = SparkFunctions.load(name);
      if (func != null) {
        return func;
      }
    }

    throw new NoSuchFunctionException(
        String.format("Cannot load function: %s.%s", name(), ident), Option.empty());
  }
}

View on GitHub (pinned to 86d9c8fc54)