XTLS/Xray-core · error

transform args are required

Error message

transform args are required

What it means

buildCustomTransform (infra/conf/transport_finalmask.go:418) requires a transform to carry at least one argument: "transform":{"op":"concat"} with missing or empty "args" returns "transform args are required". Args supply the values (bytes/str/u64/reuse/metadata/nested transform) the op operates on.

Source

Thrown at infra/conf/transport_finalmask.go:418

	if kindCount > 1 {
		return errors.New("exactly one item kind must be set")
	}
	if kindCount == 0 && capture != "" {
		return errors.New("exactly one item kind must be set")
	}

	return nil
}

func buildCustomTransform(transform *CustomTransform) (*custom.Expr, error) {
	if transform == nil {
		return nil, nil
	}
	if transform.Op == "" {
		return nil, errors.New("transform op is required")
	}
	if len(transform.Args) == 0 {
		return nil, errors.New("transform args are required")
	}

	args := make([]*custom.ExprArg, 0, len(transform.Args))
	for _, arg := range transform.Args {
		parsedArg, err := buildCustomTransformArg(arg)
		if err != nil {
			return nil, err
		}
		args = append(args, parsedArg)
	}

	return &custom.Expr{
		Op:   transform.Op,
		Args: args,
	}, nil
}

func buildCustomTransformArg(arg CustomTransformArg) (*custom.ExprArg, error) {

View on GitHub (pinned to 7d214f8b09)

Solutions

1. Provide at least one entry in "args", e.g. [{"reuse":"captured"}]
2. Give every nested transform at least one arg too
3. Drop the transform object if the item needs no computation

Example fix

// before
"transform": { "op": "concat" }
// after
"transform": { "op": "concat", "args": [ {"str":"x"}, {"reuse":"v"} ] }

// covered by checkTransform above: args.length === 0 -> throw

When it happens

Trigger: "transform":{"op":"someop"} with no "args" key, or "args":[] . Fires on the top-level transform and again on any nested arg.Transform that is non-nil but arg-less.

Common situations: Constants-only ops written without arguments; deleting an arg while debugging; nested transform scaffolding left empty after refactoring.

Related errors

• transform op is required
• transform arg must set exactly one value
• invalid randRange
• invalid variable name
• exactly one item kind must be set

AI-assisted analysis of XTLS/Xray-core@7d214f8b09 (2026-08-15). Data as JSON: /api/errors/ce9f9cea24e49dc4. Report an issue: GitHub.