alibaba/DataX · error · IllegalArgumentException

id length over limit(${maxIdLength})

Error message

id length over limit(${maxIdLength})

What it means

GdbElement.setId enforces the GDB maximum id length on every element (vertex or edge). If the resolved id string exceeds MapperConfig.getMaxIdLength(), IllegalArgumentException is thrown during record mapping — before any write to the graph database.

Source

Thrown at gdbwriter/src/main/java/com/alibaba/datax/plugin/writer/gdbwriter/model/GdbElement.java:28

import com.alibaba.datax.plugin.writer.gdbwriter.mapping.MapperConfig;

/**
 * @author jerrywang
 *
 */
public class GdbElement {
    private String id = null;
    private String label = null;
    private List<GdbProperty> properties = new LinkedList<>();

    public String getId() {
        return this.id;
    }

    public void setId(final String id) {
        final int maxIdLength = MapperConfig.getInstance().getMaxIdLength();
        if (id.length() > maxIdLength) {
            throw new IllegalArgumentException("id length over limit(" + maxIdLength + ")");
        }
        this.id = id;
    }

    public String getLabel() {
        return this.label;
    }

    public void setLabel(final String label) {
        final int maxLabelLength = MapperConfig.getInstance().getMaxLabelLength();
        if (label.length() > maxLabelLength) {
            throw new IllegalArgumentException("label length over limit(" + maxLabelLength + ")");
        }
        this.label = label;
    }

    public List<GdbProperty> getProperties() {
        return this.properties;

View on GitHub (pinned to 80ec23d5c5)

Solutions

1. Switch to a bounded synthetic id (UUID or fixed-length hash of the natural key) and store the natural key as a property for lookup
2. Pre-validate: SELECT count(*) WHERE length(id_col) > 256 must return 0 before the job
3. If a longer limit is supported by your GDB version, raise MapperConfig's maxIdLength accordingly

Example fix

// before
String id = record.getEmail();
// after
String id = "user_" + DigestUtils.md5Hex(record.getEmail());

static String safeGdbId(String naturalKey) {
    return naturalKey.length() <= MapperConfig.getInstance().getMaxIdLength()
        ? naturalKey
        : "h_" + DigestUtils.md5Hex(naturalKey);
}

static boolean isValidGdbId(String s) {
    return s != null && !s.isEmpty() && s.length() <= MapperConfig.getInstance().getMaxIdLength();
}

catch (IllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("id length over limit")) {
        // switch to hashed/synthetic ids; keep the natural key as a property for lookup
    }
}

When it happens

Trigger: Any gdbwriter import where the record's id column value is longer than maxIdLength: natural keys like emails/URLs/paths, concatenated composite keys, or untrimmed whitespace-padded keys.

Common situations: Using email or URL as the vertex id (URLs exceed 256 easily); composite keys built as a+b+c; migrating from Neo4j/RDBMS without key-length policy; edge ids are usually UUIDs (36 chars) so this mostly hits vertex ids.

Related errors

• from length over limit(${maxIdLength})
• to length over limit(${maxIdLength})
• label length over limit(${maxLabelLength})
• property key length over limit(${maxPropKeyLength})
• to or from missed in edge

AI-assisted analysis of alibaba/DataX@80ec23d5c5 (2026-08-14). Data as JSON: /api/errors/5fffc7f04612a24f. Report an issue: GitHub.