Alias '%s' either contains restricted characters or is the s

Error message

Alias '%s' either contains restricted characters or is the same as a restricted tag needed for normal operation

What it means

validator_instance.go:244 panics in RegisterAlias when the alias name is either listed in restrictedTags (a baked-in tag name like `required`, `email`) or contains restrictedTagChars (characters such as '-', '=', '.', ',' used as tag grammar). Aliases must be new, safe identifiers because the tag parser would otherwise become ambiguous or break normal tag operation. The panic is fail-fast at registration time, not validation time.

Source

Thrown at validator_instance.go:244

// allowing context.Context validation support.
func (v *Validate) RegisterValidationCtx(tag string, fn FuncCtx, callValidationEvenIfNull ...bool) error {
	var nilCheckable bool
	if len(callValidationEvenIfNull) > 0 {
		nilCheckable = callValidationEvenIfNull[0]
	}
	return v.registerValidation(tag, fn, false, nilCheckable)
}

// RegisterAlias registers a mapping of a single validation tag that
// defines a common or complex set of validation(s) to simplify adding validation
// to structs.
//
// NOTE: this function is not thread-safe it is intended that these all be registered prior to any validation
func (v *Validate) RegisterAlias(alias, tags string) {
	_, ok := restrictedTags[alias]

	if ok || strings.ContainsAny(alias, restrictedTagChars) {
		panic(fmt.Sprintf(restrictedAliasErr, alias))
	}

	v.aliases[alias] = tags
}

// RegisterStructValidation registers a StructLevelFunc against a number of types.
//
// NOTE:
// - this method is not thread-safe it is intended that these all be registered prior to any validation
func (v *Validate) RegisterStructValidation(fn StructLevelFunc, types ...interface{}) {
	v.RegisterStructValidationCtx(wrapStructLevelFunc(fn), types...)
}

// RegisterStructValidationCtx registers a StructLevelFuncCtx against a number of types and allows passing
// of contextual validation information via context.Context.
//
// NOTE:
// - this method is not thread-safe it is intended that these all be registered prior to any validation

View on GitHub (pinned to facf128d2e)

Solutions

Rename the alias to a restricted-char-free identifier that is not a baked-in tag (e.g. use camelCase or snake_case: myAlias, my_alias).
Check the name against the restrictedTags list in baked_in.go before registering.
Sanitize programmatically generated alias names (strip characters in restrictedTagChars).
If the goal is to change built-in tag behavior, wrap it differently: register your own tag name and use that in tags instead of aliasing the restricted name.
Register aliases at startup before validation so the panic surfaces early.

Example fix

// before
v.RegisterAlias("required", "min=1")      // restricted tag
v.RegisterAlias("is-positive-num", "gt=0") // contains '-'

// after
v.RegisterAlias("isPositiveNum", "gt=0")

Defensive patterns

Strategy: validation

Validate before calling

func safeRegisterAlias(v *validator.Validate, alias, tags string) (err error) {
    defer func() {
        if r := recover(); r != nil {
            err = fmt.Errorf("invalid alias %q: %v", alias, r)
        }
    }()
    v.RegisterAlias(alias, tags)
    return nil
}

Type guard

var validAliasRe = regexp.MustCompile(`^[A-Za-z_][A-Za-z0-9_]*$`)

func isSafeAlias(name string) bool {
    return validAliasRe.MatchString(name)
}

Try / catch

defer func() {
    if r := recover(); r != nil {
        err = fmt.Errorf("RegisterAlias rejected %q: %v", alias, r)
    }
}()
v.RegisterAlias(alias, tags)

Prevention

Name aliases with letters, digits, and underscore only — never kebab-case.
Check the proposed name against the restrictedTags denylist in baked_in.go first.
Do all alias registration in package init so conflicts surface at boot.
Never attempt to alias a baked-in tag name; register a new tag name instead.

When it happens

Trigger: v.RegisterAlias("required", "min=1") — overriding a baked-in tag; v.RegisterAlias("my-alias", "...") or any alias containing '=', '.', ',', '|', '-' characters; registering an alias whose name collides with any restricted tag in the denylist.

Common situations: Choosing kebab-case names for aliases out of habit; attempting to intentionally override built-in behavior via alias (not allowed — use RegisterValidation with bakedIn=false path restrictions similarly); renaming an existing alias to something containing a dash during cleanup; generating alias names programmatically from user input that includes restricted characters.

Related errors

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