apache/seatunnel · error · HugeGraphConnectorException

INVALID_GRAPH_SCHEMA

INVALID_GRAPH_SCHEMA

Error message

No read context for label '%s'.

What it means

HugeGraphSourceReader keeps a map of per-label read contexts (LabelTableContext) built at source initialization. When a split references a label that has no entry in that map, contextFor() fails fast with INVALID_GRAPH_SCHEMA rather than dereferencing null, indicating an internal inconsistency between split enumeration and context building.

Source

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

        this.context = context;
        this.sourceConfig = sourceConfig;
        this.labelContexts = labelContexts;
        this.client = client;
    }

    /**
     * The label the given split reads: a LABEL_LIST split names it directly; a SHARD split scans a
     * key range of all labels and inherits the single configured label (shard splits are only
     * created in single-label mode).
     */
    private String activeLabel(HugeGraphSourceSplit split) {
        return split.getLabel() != null ? split.getLabel() : sourceConfig.getLabel();
    }

    private LabelTableContext contextFor(String label) {
        LabelTableContext ctx = labelContexts.get(label);
        if (ctx == null) {
            throw new HugeGraphConnectorException(
                    HugeGraphConnectorErrorCode.INVALID_GRAPH_SCHEMA,
                    String.format("No read context for label '%s'.", label));
        }
        return ctx;
    }

    @Override
    public void open() {
        // Read-all mode auto-discovers each label's row type from the server, so there is no user
        // schema to validate against (it cannot mismatch). Skip validation; the reader resolves
        // each split's context by label at read time.
        if (sourceConfig.isReadAllLabels()) {
            return;
        }
        try {
            // validateLabelAndSchema triggers the lazy client connection; if it throws (unknown
            // label, type mismatch, unreachable server) the framework may not call close(), so
            // release the just-opened client here to avoid leaking connection pools/threads.

View on GitHub (pinned to cf67b549a7)

Solutions

  1. Rerun the job with the current config so splits and contexts are rebuilt consistently.
  2. Verify the label still exists in HugeGraph and matches the configured 'label' option.
  3. If recovering from a checkpoint taken with different labels/config, discard the old checkpoint and start fresh.
  4. Report as a bug if it reproduces with an unchanged config — split enumeration and context building should agree.
Defensive patterns

Strategy: try-catch

Validate before calling

// ensure split label was part of context building
if (!labelContexts.containsKey(splitLabel)) { /* rebuild/restart job */ }

Try / catch

try {
  LabelTableContext ctx = reader.contextFor(label);
} catch (HugeGraphConnectorException e) {
  if (e.getErrorCode() == INVALID_GRAPH_SCHEMA) { /* restart job / discard stale checkpoint */ }
}

Prevention

When it happens

Trigger: A SourceSplit's label (split.getLabel() or sourceConfig.getLabel()) is not a key in labelContexts; called from ctx() or propertyRowType() during read/poll processing.

Common situations: Label deleted or renamed between split enumeration and reading; mismatch between the label used when splits were created and the labels captured in contexts (e.g., config changed on restart/recovery from an old checkpoint); all-labels read where labels changed server-side mid-job.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

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