apache/seatunnel · error · HugeGraphConnectorException

ILLEGAL_CONFIG_ARGUMENT

ILLEGAL_CONFIG_ARGUMENT

Error message

Either 'mappings' or 'schema_config' must be specified. 'mappings' is the recommended option.

What it means

HugeGraphSinkConfig.resolveMappings() throws ILLEGAL_CONFIG_ARGUMENT when neither 'mappings' nor the legacy 'schema_config' option is present, since the sink cannot know how to map SeaTunnel rows onto HugeGraph vertices/edges without one of them. 'mappings' is the recommended, newer format.

Solutions

1. Add a 'mappings' list describing vertex/edge label mappings (recommended).
2. Alternatively supply the legacy 'schema_config' block if you are on an older setup.
3. Check that the option keys are not commented out or misnamed in the sink block.

Example fix

// before
HugeGraph {
  host = "hugegraph-server"
  graph_name = "hugegraph"
  # no mappings or schema_config
}
// after
HugeGraph {
  host = "hugegraph-server"
  graph_name = "hugegraph"
  mappings = [
    { source_vertex_label = "person", target_vertex_label = "person", edge_label = "knows" }
  ]
}

if (!opts.containsKey(HugeGraphSinkOptions.MAPPINGS) && !opts.containsKey(HugeGraphSinkOptions.SCHEMA_CONFIG)) { throw new IllegalArgumentException("Provide 'mappings' (recommended) or 'schema_config'"); }

// try { HugeGraphSinkConfig.of(opts); } catch (HugeGraphConnectorException e) {
//   if (e.getMessage().contains("mappings")) { /* add a mappings block before resubmitting */ } }

When it happens

Trigger: Building the sink config via of() with an empty or mappings-less options map that also lacks schema_config — e.g. an incomplete sink block or all mapping keys commented out.

Common situations: Users migrate docs/examples and delete schema_config without adding mappings, or copy a source config that has no mapping options at all.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• ILLEGAL_CONFIG_ARGUMENT
• ILLEGAL_CONFIG_ARGUMENT
• At least one sink plugin must be configured.
• At least one source plugin must be configured.
• AzureCosmosDB requires uri, endpoint, or connection string…

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

Appendix: source

Thrown at seatunnel-connectors-v2/connector-hugegraph/src/main/java/org/apache/seatunnel/connectors/seatunnel/hugegraph/config/HugeGraphSinkConfig.java:197

        boolean hasSchemaConfig =
                config.getOptional(HugeGraphSinkOptions.SCHEMA_CONFIG).isPresent();

        if (hasMappings) {
            if (hasSchemaConfig) {
                LOG.warn(
                        "Both 'mappings' and 'schema_config' are present. "
                                + "'schema_config' will be ignored. Please migrate to 'mappings'.");
            }
            return config.get(HugeGraphSinkOptions.MAPPINGS);
        }

        if (hasSchemaConfig) {
            SchemaConfig schemaConfig = config.get(HugeGraphSinkOptions.SCHEMA_CONFIG);
            sinkConfig.setSchemaConfig(schemaConfig);
            return Collections.singletonList(MappingConfig.fromLegacySchemaConfig(schemaConfig));
        }

        throw new HugeGraphConnectorException(
                HugeGraphConnectorErrorCode.ILLEGAL_CONFIG_ARGUMENT,
                "Either 'mappings' or 'schema_config' must be specified. "
                        + "'mappings' is the recommended option.");
    }

    private static void applyMappingDefaults(List<MappingConfig> mappings) {
        if (mappings == null) {
            return;
        }
        for (MappingConfig m : mappings) {
            if (m.getDateFormat() == null || m.getDateFormat().isEmpty()) {
                m.setDateFormat("yyyy-MM-dd");
            }
            // Leave timeZone unset when the user did not configure one; DataTypeUtil then falls
            // back to ZoneId.systemDefault(), matching the HugeGraph Source. Hard-coding GMT+8
            // here previously silently shifted absolute times by up to 8 hours when the Source
            // ran on a JVM whose default zone was not Asia/Shanghai.
        }

View on GitHub (pinned to cf67b549a7)