What causes "NebulaGraph sink writer is in a failed state." in apache/seatunnel?

Fix the root cause of the initial failure (check logs for the original Nebula exception) before retrying

apache/seatunnel · error · IOException

NebulaGraph sink writer is in a failed state.

Error message

NebulaGraph sink writer is in a failed state.

What it means

The writer tracks a persistent failure with a 'failed' flag; once set (e.g. after a write/flush error the connector considers fatal), ensureWritable() rejects all subsequent write() and prepareCommit() calls with this IOException. The writer is poisoned by design: after an unrecoverable write failure it refuses more data rather than risk silently dropping or corrupting records.

Solutions

Fix the root cause of the initial failure (check logs for the original Nebula exception) before retrying
Restart the task so the writer is recreated from the sink factory/restore path
Validate Nebula schema/space and credentials so the first write does not fail
Treat the writer as terminal state in wrapping code: do not reuse it after a failed write

Example fix

// before
try { writer.write(row); } catch (Exception e) { /* swallow, keep writing */ }
// after
try { writer.write(row); } catch (Exception e) {
    throw new IOException("write failed, writer is poisoned", e); // let framework recreate writer
}

Defensive patterns

Strategy: try-catch

Try / catch

try { writer.write(row); } catch (IOException e) { if (e.getMessage().contains("failed state")) { throw new IOException("writer poisoned; task must restart", e); } throw e; }

Prevention

Fix the first write failure's root cause before retrying on the same writer
Monitor Nebula health (space, schema, auth) to prevent initial failures
Do not swallow exceptions around writer.write — let the engine recreate the writer

When it happens

Trigger: Any earlier write/flush to NebulaGraph threw an exception that the writer recorded by setting failed=true, followed by another write() or prepareCommit() call on the same writer instance.

Common situations: NebulaGraph outage or auth failure mid-job followed by retry attempts on the same writer; batch insert failing on a schema mismatch and the framework retrying the checkpoint flush; long-running job whose session expired.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

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

Appendix: source

Thrown at seatunnel-connectors-v2/connector-nebulagraph/src/main/java/org/apache/seatunnel/connectors/seatunnel/nebulagraph/sink/NebulaGraphSinkWriter.java:150

            buffer.clear();
        } catch (IOException | RuntimeException e) {
            failed = true;
            throw new IOException(
                    "Failed to write "
                            + buffer.size()
                            + " vertices to NebulaGraph tag '"
                            + config.getTag()
                            + "'. The writer will not retry this batch during close.",
                    e);
        }
    }

    private void ensureWritable() throws IOException {
        if (closed) {
            throw new IOException("NebulaGraph sink writer is already closed.");
        }
        if (failed) {
            throw new IOException("NebulaGraph sink writer is in a failed state.");
        }
    }

    private IOException unsupportedRowKind(RowKind rowKind) {
        return new IOException(
                "Row kind "
                        + rowKind
                        + " is not supported in NebulaGraph "
                        + config.getWriteMode()
                        + " mode.");
    }
}

View on GitHub (pinned to cf67b549a7)