go-playground/validator · error

Bad param number for excluded_unless %s

Error message

Bad param number for excluded_unless %s

What it means

excluded_unless excludes the field unless all listed fields equal their values. Like the other *_if/*_unless conditionals, its params must be complete field,value pairs; an odd count panics at baked_in.go:2194.

Source

Thrown at baked_in.go:2194

func skipUnless(fl FieldLevel) bool {
	params := parseOneOfParam2(fl.Param())
	if len(params)%2 != 0 {
		panic(fmt.Sprintf("Bad param number for skip_unless %s", fl.FieldName()))
	}
	for i := 0; i < len(params); i += 2 {
		if !requireCheckFieldValue(fl, params[i], params[i+1], false) {
			return true
		}
	}
	return hasValue(fl)
}

// excludedUnless is the validation function
// The field under validation must not be present or is empty unless all the other specified fields are equal to the value following with the specified field.
func excludedUnless(fl FieldLevel) bool {
	params := parseOneOfParam2(fl.Param())
	if len(params)%2 != 0 {
		panic(fmt.Sprintf("Bad param number for excluded_unless %s", fl.FieldName()))
	}
	for i := 0; i < len(params); i += 2 {
		if requireCheckFieldValue(fl, params[i], params[i+1], false) {
			return true
		}
	}

	return !hasValue(fl)
}

// excludedWith is the validation function
// The field under validation must not be present or is empty if any of the other specified fields are present.
func excludedWith(fl FieldLevel) bool {
	params := parseOneOfParam2(fl.Param())
	for _, param := range params {
		if !requireCheckFieldKind(fl, param, true) {
			return !hasValue(fl)
		}

View on GitHub (pinned to facf128d2e)

Solutions

  1. Provide field,value pairs: `excluded_unless=Status,archived`.
  2. Validate the comma-split count is even.
  3. Switch to excluded_without for presence-only semantics.
  4. Unit-test the struct tag.

Example fix

// before
Status  string
Deleted string `validate:"excluded_unless=Status"`

// after
Status  string
Deleted string `validate:"excluded_unless=Status,active"`
Defensive patterns

Strategy: validation

Validate before calling

func checkExcludedUnlessTag(tagValue string) error {
    parts := strings.Split(tagValue, ",")
    if len(parts)%2 != 0 {
        return fmt.Errorf("excluded_unless needs field,value pairs; got %d params in %q", len(parts), tagValue)
    }
    return nil
}

Try / catch

func safeValidate(v *Validate, s interface{}) (err error) {
    defer func() {
        if r := recover(); r != nil {
            err = fmt.Errorf("validator panic (check excluded_unless params): %v", r)
        }
    }()
    return v.Struct(s)
}

Prevention

When it happens

Trigger: Tag like `excluded_unless=Status` or `excluded_unless=A,1,B` — dangling field name without a value, or an unescaped comma making the count odd.

Common situations: Forgetting the value half of a pair; copying syntax from excluded_without (bare field list); generated tags with malformed joins.

Related errors

AI-assisted analysis of go-playground/validator@facf128d2e (2026-09-02). Data as JSON: /api/errors/b65f08e476878995. Report an issue: GitHub.