apache/seatunnel · error · Neo4jConnectorException

ILLEGAL_ARGUMENT

ILLEGAL_ARGUMENT

Error message

Key Type of MapType must String type

What it means

The Neo4j reader can only convert MAP-typed SeaTunnel columns whose key type is STRING, since Neo4j returns property maps keyed by String. convertType throws Neo4jConnectorException (ILLEGAL_ARGUMENT) when a schema declares a map with a non-String key type.

Solutions

1. Change the schema column type to map<string, T> so the key type is STRING.
2. Flatten the map into individual columns in the Cypher query (e.g. RETURN m.key1 AS key1).
3. If non-string keys are essential, cast keys to string in Cypher (toString(k)) and use map<string,T>.

Example fix

// before
columns = [{ name = props, type = map<int, string> }]
// after
columns = [{ name = props, type = map<string, string> }]

columns.forEach(c -> {
  if (c.type.startsWith("map<") && !c.type.toLowerCase().startsWith("map<string")) {
    throw new IllegalArgumentException("Neo4j map keys must be string: " + c.name);
  }
});

static boolean hasStringMapKey(SeaTunnelDataType<?> t) {
  return !(t instanceof MapType) || ((MapType<?, ?>) t).getKeyType().equals(BasicType.STRING_TYPE);
}

try {
  row = convertRecord(...);
} catch (Neo4jConnectorException e) {
  if ("ILLEGAL_ARGUMENT".equals(e.getSeaTunnelErrorCode().getCode())) {
    // fix schema: use map<string, T>
  }
  throw e;
}

When it happens

Trigger: convertType (called from convertRecord, recursively from convertType, or list) encounters a MapType whose getKeyType() != BasicType.STRING_TYPE while converting a Neo4j Value.

Common situations: Users declare a schema column as map<int,int> or map<string->other> in the Neo4j source schema, but Neo4j property maps are always string-keyed; schema copied from another connector supporting arbitrary key types.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• Cannot convert to struct:
• COMMON-07
• CONFIG_VALIDATION_FAILED
• Expected Array type but got:
• Map type requires Map value, got

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

Appendix: source

Thrown at seatunnel-connectors-v2/connector-neo4j/src/main/java/org/apache/seatunnel/connectors/seatunnel/neo4j/source/Neo4jSourceReader.java:205

            case BOOLEAN:
                return value.asBoolean();
            case BIGINT:
                return value.asLong();
            case DOUBLE:
                return value.asDouble();
            case NULL:
                return null;
            case BYTES:
                return value.asByteArray();
            case DATE:
                return value.asLocalDate();
            case TIME:
                return value.asLocalTime();
            case TIMESTAMP:
                return value.asLocalDateTime();
            case MAP:
                if (!((MapType<?, ?>) dataType).getKeyType().equals(BasicType.STRING_TYPE)) {
                    throw new Neo4jConnectorException(
                            CommonErrorCodeDeprecated.ILLEGAL_ARGUMENT,
                            "Key Type of MapType must String type");
                }
                final SeaTunnelDataType<?> valueType = ((MapType<?, ?>) dataType).getValueType();
                return value.asMap(v -> valueType.getTypeClass().cast(convertType(valueType, v)));
            case ARRAY:
                final SeaTunnelDataType<?> elementType =
                        ((ArrayType<?, ?>) dataType).getElementType();
                final List<?> list =
                        value.asList(
                                v -> elementType.getTypeClass().cast(convertType(elementType, v)));
                final Object array = Array.newInstance(elementType.getTypeClass(), list.size());
                for (int i = 0; i < list.size(); i++) {
                    Array.set(array, i, list.get(i));
                }
                return array;
            case INT:
                return value.asInt();

View on GitHub (pinned to cf67b549a7)