alibaba/DataX · error · IllegalArgumentException

property key length over limit(${maxPropKeyLength})

Error message

property key length over limit(${maxPropKeyLength})

What it means

GdbElement.addProperty rejects property keys longer than MapperConfig.getMaxPropKeyLength() with IllegalArgumentException. Note an adjacent bug: the string *value* length check compares against maxPropKeyLength, not maxPropValueLength, but throws the 'property value length over limit' message printing maxPropValueLength — so over-long string values may be rejected by the wrong limit or wrongly pass.

Source

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

        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;
    }

    public void addProperty(final String propKey, final Object propValue, final PropertyType card) {
        if (propKey == null || propValue == null) {
            return;
        }

        final int maxPropKeyLength = MapperConfig.getInstance().getMaxPropKeyLength();
        if (propKey.length() > maxPropKeyLength) {
            throw new IllegalArgumentException("property key length over limit(" + maxPropKeyLength + ")");
        }
        if (propValue instanceof String) {
            final int maxPropValueLength = MapperConfig.getInstance().getMaxPropValueLength();
            if (((String)propValue).length() > maxPropKeyLength) {
                throw new IllegalArgumentException("property value length over limit(" + maxPropValueLength + ")");
            }
        }

        this.properties.add(new GdbProperty(propKey, propValue, card));
    }

    public void addProperty(final String propKey, final Object propValue) {
        addProperty(propKey, propValue, PropertyType.single);
    }

    @Override
    public String toString() {
        final StringBuffer sb = new StringBuffer(this.id + "[" + this.label + "]{");

View on GitHub (pinned to 80ec23d5c5)

Solutions

1. Shorten/mapping-rename property keys to a bounded vocabulary (GDB recommends short keys — they are stored per element)
2. For long text values, store externally (OSS/S3) and keep a reference in the property, or truncate
3. If you control the build, fix the value-check bug: compare ((String)propValue).length() > maxPropValueLength, not maxPropKeyLength
4. Pre-scan source column names and lengths before migration

Example fix

// before (in GdbElement.addProperty)
if (((String)propValue).length() > maxPropKeyLength) {
    throw new IllegalArgumentException("property value length over limit(" + maxPropValueLength + ")");
}
// after
if (((String)propValue).length() > maxPropValueLength) {
    throw new IllegalArgumentException("property value length over limit(" + maxPropValueLength + ")");
}

static String safePropKey(String key, int max) {
    return key.length() <= max ? key : "p_" + DigestUtils.md5Hex(key);
}
// NOTE: also beware the value-length bug: values are compared to maxPropKeyLength, not maxPropValueLength

static boolean isValidPropKey(String k) {
    return k != null && !k.isEmpty() && k.length() <= MapperConfig.getInstance().getMaxPropKeyLength();
}

catch (IllegalArgumentException e) {
    String m = e.getMessage();
    if (m != null && m.startsWith("property key length over limit")) { /* shorten keys */ }
    else if (m != null && m.startsWith("property value length over limit")) { /* offload/truncate long text; remember the threshold check itself is buggy */ }
}

When it happens

Trigger: Property keys built dynamically from data (column-name arrays, composite property names like 'addr.line1.city') exceeding the key-length limit; string property values longer than the limit hitting the (buggy) value check immediately after this key check.

Common situations: Flattening nested JSON into dotted property keys; i18n/long descriptive column names mapped straight to GDB property keys; large text columns (descriptions, bodies) as string property values tripping the value-length branch with a misleading threshold.

Related errors

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

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