apache/seatunnel · error · IllegalArgumentException

NebulaGraph string vertex IDs must not contain unsupported…

Error message

NebulaGraph string vertex IDs must not contain unsupported control characters.

What it means

When serializing a string vertex ID to nGQL, formatVid() escapes common control characters but throws this IllegalArgumentException for any other ISO control character (0x00-0x1F, 0x7F) it cannot safely escape. NebulaGraph string VIDs in quoted nGQL cannot contain raw control characters, so the connector fails fast to avoid producing corrupt or injectable statements.

Solutions

1. Sanitize string vertex IDs before writing, stripping or replacing control characters
2. Convert the vertex ID column to a numeric type if Nebula VID type is INT
3. Fix the upstream source/parser that is emitting control characters
4. Escape expected control characters explicitly in your transform before the sink

Example fix

// before
String vid = row.getField(0).toString();
// after
String vid = row.getField(0).toString().replaceAll("\\p{Cntrl}", "");

static boolean isSafeVid(String vid) { return vid.chars().noneMatch(Character::isISOControl); }

String safeVid(String vid) { return vid == null ? null : vid.replaceAll("\\p{Cntrl}", ""); }

try { sink.write(row); } catch (IllegalArgumentException e) { if (e.getMessage().contains("control characters")) { /* sanitize and rewrite or dead-letter */ } else { throw e; } }

When it happens

Trigger: Writing a vertex whose SeaTunnel string ID column contains control characters such as \u0000, \u0001, or other non-printable bytes not in the escaped set (\n, \r, \t, \b, \f, quote, backslash).

Common situations: Source data from binary logs or legacy systems with embedded NUL/control bytes; user IDs or keys copied with invisible characters; data corruption from upstream parsing.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Cannot build a NebulaGraph request for an empty batch.
• INVALID_CONFIG
• NebulaGraph sink writer is already closed.
• NebulaGraph sink writer is in a failed state.
• ACKNOWLEDGE_FAILED

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

Appendix: source

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

                    break;
                case '\n':
                    escaped.append("\\n");
                    break;
                case '\r':
                    escaped.append("\\r");
                    break;
                case '\t':
                    escaped.append("\\t");
                    break;
                case '\b':
                    escaped.append("\\b");
                    break;
                case '\f':
                    escaped.append("\\f");
                    break;
                default:
                    if (Character.isISOControl(character)) {
                        throw new IllegalArgumentException(
                                "NebulaGraph string vertex IDs must not contain unsupported control characters.");
                    }
                    escaped.append(character);
            }
        }
        return escaped.append('"').toString();
    }

    private static String quoteIdentifier(String identifier) {
        return "`" + validateIdentifier(identifier) + "`";
    }

    private static String validateIdentifier(String identifier) {
        if (identifier == null || !IDENTIFIER.matcher(identifier).matches()) {
            throw new NebulaGraphConnectorException(
                    NebulaGraphConnectorErrorCode.INVALID_CONFIG,
                    "NebulaGraph tag and property names must contain only letters, digits, or underscores and must not start with a digit: "
                            + identifier);

View on GitHub (pinned to cf67b549a7)