alibaba/DataX · error · RuntimeException

TRANSFORMER_ILLEGAL_PARAMETER

TRANSFORMER_ILLEGAL_PARAMETER

Error message

dx_substr paras must be 3

What it means

Thrown by the dx_substr transformer when its paras array does not contain exactly 3 elements. dx_substr expects [columnIndex(int), startIndex(String), length(String)]. The length check runs first in the parameter-parsing try block and is reported as TRANSFORMER_ILLEGAL_PARAMETER together with the parsed paras list.

Source

Thrown at core/src/main/java/com/alibaba/datax/core/transport/transformer/SubstrTransformer.java:29

/**
 * no comments.
 * Created by liqiang on 16/3/4.
 */
public class SubstrTransformer extends Transformer {
    public SubstrTransformer() {
        setTransformerName("dx_substr");
    }

    @Override
    public Record evaluate(Record record, Object... paras) {

        int columnIndex;
        int startIndex;
        int length;

        try {
            if (paras.length != 3) {
                throw new RuntimeException("dx_substr paras must be 3");
            }

            columnIndex = (Integer) paras[0];
            startIndex = Integer.valueOf((String) paras[1]);
            length = Integer.valueOf((String) paras[2]);

        } catch (Exception e) {
            throw DataXException.asDataXException(TransformerErrorCode.TRANSFORMER_ILLEGAL_PARAMETER, "paras:" + Arrays.asList(paras).toString() + " => " + e.getMessage());
        }

        Column column = record.getColumn(columnIndex);

        try {
            String oriValue = column.asString();
            //如果字段为空，跳过subStr处理
            if(oriValue == null){
                return record;
            }

View on GitHub (pinned to 80ec23d5c5)

Solutions

1. Provide exactly 3 parameters: column index (int), startIndex (numeric string), length (numeric string).
2. To take the rest of the string, pass a large length (e.g. "999999") — the code clamps to the string end when startIndex+length >= value length.
3. Use the 'paras:[...]' echo in the error message to confirm what DataX actually parsed.

Example fix

// before
"paras": [2, "1"]
// after
"paras": [2, "1", "999999"]

Object[] paras = ...;
if (paras.length != 3) throw new IllegalArgumentException("dx_substr needs [columnIndex, startIndex, length]");

When it happens

Trigger: A job JSON declares dx_substr with 2 or 4 parameters, e.g. "paras": [0, "1"] (missing length) or [0, "1", "4", "extra"]. Any deviation from 3 elements throws before any record is processed.

Common situations: Assuming substring-to-end needs no length argument, copying the 4-element dx_replace parameter shape, or a malformed JSON array that yields a different element count.

Related errors

• dx_pad first para(%s) support l or r
• TRANSFORMER_ILLEGAL_PARAMETER
• TRANSFORMER_RUN_EXCEPTION
• 您提供的配置文件有误. 路径[%s]需要配置Json格式的Map对象，但该节点发现实际类型是[%s]. 请检查您的配置并
• 您提供的配置文件有误. 路径[%s]值为null，datax无法识别该配置. 请检查您的配置并作出修改.

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