{"record":{"id":"447555a320e9004b","repo":"apache/beam","slug":"failed-to-instantiate-lineage-implementation-s-the-class","errorCode":null,"errorMessage":"Failed to instantiate lineage implementation: %s. The class must have a public constructor accepting (PipelineOptions, Lineage.LineageDirection).","messagePattern":"Failed to instantiate lineage implementation: (.+?)\\. The class must have a public constructor accepting \\(PipelineOptions, Lineage\\.LineageDirection\\)\\.","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/metrics/Lineage.java","lineNumber":108,"sourceCode":"    }\n    // When no type is requested, preserve whatever is already initialized.\n    // When a type is requested, only re-init if it differs from the active type.\n    return requestedType == null || requestedType.equals(currentLineageType);\n  }\n\n  private static Lineage createLineage(PipelineOptions options, LineageDirection direction) {\n    Class<? extends LineageBase> lineageClass = options.as(LineageOptions.class).getLineageType();\n\n    if (lineageClass != null) {\n      try {\n        LineageBase lineage =\n            lineageClass\n                .getDeclaredConstructor(PipelineOptions.class, LineageDirection.class)\n                .newInstance(options, direction);\n        LOG.info(\"Using {} for lineage direction {}\", lineageClass.getName(), direction);\n        return new Lineage(lineage);\n      } catch (ReflectiveOperationException e) {\n        throw new IllegalArgumentException(\n            \"Failed to instantiate lineage implementation: \"\n                + lineageClass.getName()\n                + \". The class must have a public constructor accepting \"\n                + \"(PipelineOptions, Lineage.LineageDirection).\",\n            e);\n      }\n    }\n\n    LOG.debug(\"Using default Metrics-based lineage for direction {}\", direction);\n    LineageBase defaultLineage =\n        MetricsFlag.lineageRollupEnabled()\n            ? new BoundedTrieMetricsLineage(options, direction)\n            : new StringSetMetricsLineage(options, direction);\n    return new Lineage(defaultLineage);\n  }\n\n  /** {@link Lineage} representing sources and optionally side inputs. */\n  @SuppressFBWarnings(","sourceCodeStart":90,"sourceCodeEnd":126,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/metrics/Lineage.java#L90-L126","documentation":"Beam's Lineage class loads a user-configured lineage implementation class reflectively. createLineage throws IllegalArgumentException when the configured class cannot be instantiated because it lacks a public constructor taking (PipelineOptions, Lineage.LineageDirection).","triggerScenarios":"Setting the lineage implementation option (via PipelineOptions) to a class whose constructor signature does not match (PipelineOptions, LineageDirection), is not public, or is abstract/missing.","commonSituations":"Upgrading Beam where the Lineage SPI contract changed, hand-rolled lineage classes with no-arg constructors, or passing a private nested class without a public constructor.","solutions":["Add or fix a public constructor on the lineage class accepting exactly (PipelineOptions, Lineage.LineageDirection).","Verify the fully-qualified class name configured for lineage is correct and on the classpath.","Make the class public and non-abstract (and its constructor public).","Check the Beam version's Lineage SPI signature if migrating code from an older release."],"exampleFix":"// before\nprivate MyLineage() {}\n// after\npublic MyLineage(PipelineOptions options, Lineage.LineageDirection direction) {\n  // init\n}","handlingStrategy":"validation","validationCode":"Class<?> c = Class.forName(lineageClassName); c.getDeclaredConstructor(PipelineOptions.class, Lineage.LineageDirection.class);","typeGuard":null,"tryCatchPattern":"try { configureLineage(options); } catch (IllegalArgumentException e) { LOG.error(\"lineage class invalid: \" + e.getMessage(), e); throw e; }","preventionTips":["Follow the documented constructor signature (PipelineOptions, LineageDirection)","Keep lineage implementation classes public and non-abstract","Add a startup smoke test that instantiates the class reflectively"],"tags":["apache-beam","reflection","lineage"],"backgroundTag":"invalid-constructor-argument","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}