What causes "Invalid argument ${argsStr}, should have 2 parts" in apache/iceberg?

Write transform args as exactly two parts: "bucket(16,user_id)", "truncate(10,name)".

apache/iceberg · error · IllegalArgumentException

Invalid argument ${argsStr}, should have 2 parts

Error message

Invalid argument ${argsStr}, should have 2 parts

What it means

transformArgPair parses the arguments of a parameterized partition transform (e.g. bucket[N], truncate[W]) expecting exactly one comma-separated pair: a column name and an integer width/count. Any other arity throws IllegalArgumentException.

Source

Thrown at kafka-connect/kafka-connect/src/main/java/org/apache/iceberg/connect/data/SchemaUtils.java:210

                {
                  Pair<String, Integer> args = transformArgPair(matcher.group(2));
                  specBuilder.truncate(args.first(), args.second());
                  break;
                }
              default:
                throw new UnsupportedOperationException("Unsupported transform: " + transform);
            }
          } else {
            specBuilder.identity(partitionField);
          }
        });
    return specBuilder.build();
  }

  private static Pair<String, Integer> transformArgPair(String argsStr) {
    List<String> parts = Splitter.on(',').splitToList(argsStr);
    if (parts.size() != 2) {
      throw new IllegalArgumentException("Invalid argument " + argsStr + ", should have 2 parts");
    }
    return Pair.of(parts.get(0).trim(), Integer.parseInt(parts.get(1).trim()));
  }

  static Type toIcebergType(Schema valueSchema, IcebergSinkConfig config) {
    return new SchemaGenerator(config).toIcebergType(valueSchema);
  }

  static Type inferIcebergType(Object value, IcebergSinkConfig config) {
    return new SchemaGenerator(config).inferIcebergType(value);
  }

  static class SchemaGenerator {

    private int fieldId = 1;
    private final IcebergSinkConfig config;

    SchemaGenerator(IcebergSinkConfig config) {

View on GitHub (pinned to 86d9c8fc54)

Solutions

Write transform args as exactly two parts: "bucket(16,user_id)", "truncate(10,name)".
Remove extra commas or missing numeric argument.
Test the config on a staging connector; the error names the offending argument string.

Example fix

// before
"iceberg.partition-by": "bucket(user_id)"
// after
"iceberg.partition-by": "bucket(16,user_id)"

Defensive patterns

Strategy: validation

Validate before calling

String args = expr.substring(expr.indexOf('(') + 1, expr.length() - 1);
if (expr.contains("(") && args.split(",").length != 2)
  throw new ConfigException("Transform needs exactly 2 args: " + expr);

Try / catch

try { spec = SchemaUtils.createPartitionSpec(schema, List.of("bucket(16,user_id)")); }
catch (IllegalArgumentException e) { throw new ConfigException(e.getMessage(), e); }

Prevention

Always include the numeric argument: bucket(N,col), truncate(W,col)
Avoid spaces/extra commas inside transform args
Lint connector configs for the partition-by syntax

When it happens

Trigger: iceberg.partition-by containing "bucket(col)" without N, "truncate(col,10,extra)", or a stray comma like "bucket(col,,16)".

Common situations: Hand-edited connector configs; copied examples missing the bucket count; commas inside quoted defaults.

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

AI-assisted analysis of apache/iceberg@86d9c8fc54 (2026-09-12). Data as JSON: /api/errors/76c0702a57e14bfc. Report an issue: GitHub.