apache/seatunnel · error · HugeGraphConnectorException

ILLEGAL_CONFIG_ARGUMENT

ILLEGAL_CONFIG_ARGUMENT

Error message

'schema' cannot be combined with reading all labels (option 'label' omitted): a single schema cannot describe multiple labels. Set 'label' to use 'schema', or drop 'schema' to auto-discover every label.

What it means

When the HugeGraph source is configured to read ALL labels of a type (option 'label' omitted), it builds one CatalogTable per discovered label. An explicit 'schema' option describes a single label's columns, which is meaningless and ambiguous across multiple labels, so the factory rejects the combination up front with ILLEGAL_CONFIG_ARGUMENT.

Source

Thrown at seatunnel-connectors-v2/connector-hugegraph/src/main/java/org/apache/seatunnel/connectors/seatunnel/hugegraph/source/HugeGraphSourceFactory.java:151

        final Map<String, LabelTableContext> contexts = labelContexts;
        final HugeGraphSourceConfig cfg = sourceConfig;
        return () ->
                (SeaTunnelSource<T, SplitT, StateT>) new HugeGraphSource(tables, contexts, cfg);
    }

    /**
     * Read-all mode: discover every label of {@code labelType} from the server and build one
     * produced {@link CatalogTable} + one {@link LabelTableContext} per label. Rejects {@code
     * schema}/{@code filter} (neither can describe multiple heterogeneous labels) and an empty
     * graph up front. Returns the read-all {@link HugeGraphSourceConfig}.
     */
    private HugeGraphSourceConfig buildReadAllTables(
            ReadonlyConfig options,
            MappingConfig.LabelType labelType,
            List<CatalogTable> catalogTables,
            Map<String, LabelTableContext> labelContexts) {
        if (options.getOptional(ConnectorCommonOptions.SCHEMA).isPresent()) {
            throw new HugeGraphConnectorException(
                    HugeGraphConnectorErrorCode.ILLEGAL_CONFIG_ARGUMENT,
                    "'schema' cannot be combined with reading all labels (option 'label' omitted): "
                            + "a single schema cannot describe multiple labels. Set 'label' to use "
                            + "'schema', or drop 'schema' to auto-discover every label.");
        }
        boolean hasFilter =
                options.getOptional(HugeGraphSourceOptions.FILTER)
                        .map(filter -> !filter.isEmpty())
                        .orElse(false);
        if (hasFilter) {
            throw new HugeGraphConnectorException(
                    HugeGraphConnectorErrorCode.ILLEGAL_CONFIG_ARGUMENT,
                    "'filter' cannot be combined with reading all labels (option 'label' omitted): "
                            + "a property-equality filter assumes the property exists on every "
                            + "label. Set 'label' to use 'filter'.");
        }
        HugeGraphClient client = new HugeGraphClient(HugeGraphConnectionConfig.of(options));
        List<String> labels;

View on GitHub (pinned to cf67b549a7)

Solutions

1. Remove the 'schema' option to let the connector auto-discover each label's columns.
2. Add a 'label' option to pin the read to a single label, then 'schema' becomes valid.
3. Split into multiple source jobs, one per label, each with its own 'label' and optional 'schema'.

Example fix

// before
source {
  HugeGraph {
    schema = "person-schema"
    # label omitted -> reads all labels
  }
}
// after
source {
  HugeGraph {
    label = "person"
    schema = "person-schema"
  }
}

// reject before submit
if (config.schema != null && config.label == null) {
  throw new IllegalArgumentException("'schema' requires 'label'");
}

try {
  factory.createSource(config);
} catch (HugeGraphConnectorException e) {
  if (e.getErrorCode() == ILLEGAL_CONFIG_ARGUMENT) { /* fix config */ }
}

When it happens

Trigger: Running a HugeGraph source job without the 'label' option (all-labels read) while also setting 'schema' in the config; HugeGraphSourceFactory.createSource() calls buildReadAllTables(), which detects SCHEMA present and throws.

Common situations: Copy-pasting a single-label config and removing only 'label'; assuming 'schema' acts as a global schema override; migration from single-label configs to all-label reads.

Related errors

• ILLEGAL_CONFIG_ARGUMENT
• INVALID_GRAPH_SCHEMA
• HugeGraphConnectorErrorCode.INVALID_GRAPH_SCHEMA
• CONFIG_VALIDATION_FAILED
• Schema config can not be empty

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/fe41c76c14d5ba81. Report an issue: GitHub.