apache/seatunnel · error · Neo4jConnectorException

DATE_BASE_ERROR

DATE_BASE_ERROR

Error message

${e.getMessage()}

What it means

writeByQuery() runs the query inside a Neo4j write transaction; when the server responds with an org.neo4j.driver.exceptions.Neo4jException (execution error such as syntax error, constraint violation, or connectivity failure surfaced by the driver), it is rethrown as Neo4jConnectorException with DATE_BASE_ERROR and the server's message. This wraps any database-side rejection of the Cypher statement.

Source

Thrown at seatunnel-connectors-v2/connector-neo4j/src/main/java/org/apache/seatunnel/connectors/seatunnel/neo4j/sink/Neo4jSinkWriter.java:130

        } catch (ClientException e) {
            log.error("Failed to build cypher statement", e);
            throw new Neo4jConnectorException(
                    SeaTunnelAPIErrorCode.CONFIG_VALIDATION_FAILED,
                    String.format(
                            "PluginName: %s, PluginType: %s, Message: %s",
                            PLUGIN_NAME, PluginType.SINK, e.getMessage()));
        }
    }

    private void writeByQuery(Query query) {
        try {
            session.writeTransaction(
                    tx -> {
                        tx.run(query);
                        return null;
                    });
        } catch (Neo4jException e) {
            throw new Neo4jConnectorException(
                    Neo4jConnectorErrorCode.DATE_BASE_ERROR, e.getMessage());
        }
    }

    @Override
    public Optional<Void> prepareCommit() throws IOException {
        return Optional.empty();
    }

    @Override
    public void abortPrepare() {}

    @Override
    public void close() throws IOException {
        // writeByQuery rethrows as Neo4jConnectorException, so a failing final flush must not be
        // allowed to skip the session and the driver, or the driver's connection pool and event
        // loop are leaked for the lifetime of the task. Every step runs, and the first failure is
        // the one that propagates: later ones are attached to it as suppressed.

View on GitHub (pinned to cf67b549a7)

Solutions

1. Read the wrapped e.getMessage() for the Neo4j server error code and fix the query accordingly
2. Validate Cypher syntax in Neo4j Browser with sample batch data
3. Handle constraint violations by deduplicating data or using MERGE instead of CREATE
4. Check Neo4j availability/connectivity settings if the error is transient, and rely on SeaTunnel retry/restore

Example fix

// before
query = "CREATE (n:Person {id: $id})" // fails on duplicate id constraint
// after
query = "MERGE (n:Person {id: $id})"

try { sink.write(row); } catch (Neo4jConnectorException e) { /* DATE_BASE_ERROR: inspect message for Neo4j status code */ if (isTransient(e.getMessage())) retry(); else throw e; }

When it happens

Trigger: Executing Cypher against a Neo4j instance that returns Neo4jException: invalid Cypher syntax, missing label/property references, constraint violations (unique constraints), database unavailable, or transaction termination.

Common situations: Typo in the query configured in the sink; writing duplicates that violate a unique constraint; Neo4j restart/timeout during a long batch; wrong database name in the URI.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

• CONFIG_VALIDATION_FAILED
• CONFIG_VALIDATION_FAILED
• Failed to close Neo4j sink writer.
• CONFIG_VALIDATION_FAILED
• READER_OPERATION_FAILED

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