apache/seatunnel · error · Neo4jConnectorException

CONFIG_VALIDATION_FAILED

CONFIG_VALIDATION_FAILED

Error message

PluginName: %s, PluginType: %s, Message: %s

What it means

Neo4jSinkWriter.batchQuery() wraps the buffered parameters and the configured Cypher query into an org.neo4j.driver Query. If the Neo4j driver's Values.parameters() or Query construction raises a ClientException (e.g. invalid parameter types such as unsupported nested values), the writer rethrows it as Neo4jConnectorException with CONFIG_VALIDATION_FAILED, prefixing the plugin name, type, and the driver's message.

Source

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

        writeBuffer.add(new SeaTunnelRowNeo4jValue(seaTunnelRowType, element));
        tryWriteByBatchSize();
    }

    private void tryWriteByBatchSize() {
        if (!writeBuffer.isEmpty() && writeBuffer.size() >= maxBatchSize) {
            Query query = batchQuery();
            writeByQuery(query);
            writeBuffer.clear();
        }
    }

    private Query batchQuery() {
        try {
            Value batchValues = Values.parameters(CypherEnum.BATCH.getValue(), writeBuffer);
            return new Query(neo4jSinkQueryInfo.getQuery(), batchValues);
        } 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());
        }

View on GitHub (pinned to cf67b549a7)

Solutions

  1. Inspect the wrapped driver message (the 'Message: %s' part) for the specific parameter or syntax problem
  2. Convert buffered fields to Neo4j-supported types (primitives, String, lists, maps of primitives) before write
  3. Validate the Cypher query syntax independently (e.g. in Neo4j Browser)
  4. Log/inspect writeBuffer contents to find the offending value

Example fix

// before
row.getField(2) // SeaTunnel Decimal -> unsupported parameter
// after
((Decimal) row.getField(2)).toBigDecimal().doubleValue() // convert to supported type
Defensive patterns

Strategy: try-catch

Validate before calling

// pre-check that buffered values are Neo4j-serializable primitives/lists/maps before write

Try / catch

try { writer.write(row); } catch (Neo4jConnectorException e) { if (e.getMessage().contains("PluginName")) { log.error("cypher build failed: {}", e.getMessage()); } throw e; }

Prevention

When it happens

Trigger: writeBuffer containing values the Neo4j driver cannot serialize into query parameters (unsupported types, deeply nested SeaTunnel values); a malformed query string causing the driver to reject the Query before execution.

Common situations: Passing SeaTunnel Map/Array fields that map to unsupported parameter types; query text with syntax problems caught at construction; upgrading the driver where serialization rules tightened.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

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