kataras/iris · warning · ErrParamNotAlphabetical

%s: %w

Error message

%s: %w

What it means

The 'alphabetical' macro fails a route parameter that does not match ^[a-zA-Z ]+$, returning '<value>: parameter is not alphabetical' (wrapping ErrParamNotAlphabetical). This surfaces as a 404-style param-type mismatch at request time (or as the macro error when params are evaluated manually).

Source

Thrown at macro/macros.go:385

	// or "0" or "f" or "F" or "FALSE" or "false" or "False".
	Bool = NewMacro("bool", "boolean", false, false, false, func(paramValue string) (any, bool) {
		// a simple if statement is faster than regex ^(true|false|True|False|t|0|f|FALSE|TRUE)$
		// in this case.
		v, err := strconv.ParseBool(paramValue)
		if err != nil {
			return err, false
		}
		return v, true
	})

	// ErrParamNotAlphabetical is fired when the parameter value is not an alphabetical text.
	ErrParamNotAlphabetical = errors.New("parameter is not alphabetical")
	alphabeticalEval        = MustRegexp("^[a-zA-Z ]+$")
	// Alphabetical letter type
	// letters only (upper or lowercase)
	Alphabetical = NewMacro("alphabetical", "", "", false, false, func(paramValue string) (any, bool) {
		if !alphabeticalEval(paramValue) {
			return fmt.Errorf("%s: %w", paramValue, ErrParamNotAlphabetical), false
		}
		return paramValue, true
	})

	// ErrParamNotFile is fired when the parameter value is not a form of a file.
	ErrParamNotFile = errors.New("parameter is not a file")
	fileEval        = MustRegexp("^[a-zA-Z0-9_.-]*$")
	// File type
	// letters (upper or lowercase)
	// numbers (0-9)
	// underscore (_)
	// dash (-)
	// point (.)
	// no spaces! or other character
	File = NewMacro("file", "", "", false, false, func(paramValue string) (any, bool) {
		if !fileEval(paramValue) {
			return fmt.Errorf("%s: %w", paramValue, ErrParamNotFile), false
		}

View on GitHub (pinned to 7bedaf55a0)

Solutions

1. Relax the param type to {param:string} if any text should be accepted.
2. Keep alphabetical but validate input in the handler and return a helpful 400 for invalid values.
3. Add an alternative route with a wider macro (e.g. {name:string regexp(^[a-zA-Z-]+$)}) if dashes must be allowed.
4. Sanitize/normalize input values client-side to letters-only where applicable.

Example fix

// before
app.Get("/hello/{name:alphabetical}", h) // rejects "john-doe"
// after
app.Get("/hello/{name:string regexp(^[a-zA-Z- ]+$)}", h)

var alphabeticalRe = regexp.MustCompile(`^[a-zA-Z ]+$`)
func isAlphabetical(s string) bool { return alphabeticalRe.MatchString(s) }
// client/handler pre-check before relying on the route
if !isAlphabetical(param) { /* return 400 or redirect */ }

func isAlphabeticalParam(v string) bool {
    for _, r := range v {
        if !(r >= 'a' && r <= 'z' || r >= 'A' && r <= 'Z' || r == ' ') { return false }
    }
    return len(v) > 0
}

// at request time the router returns 404 for mismatched macros; handle it:
app.OnErrorCode(iris.StatusNotFound, func(ctx iris.Context) {
    p := ctx.Path()
    if strings.Contains(p, "/hello/") {
        ctx.JSON(iris.Map{"error": "name must contain letters and spaces only"})
        return
    }
    ctx.JSON(iris.Map{"error": "not found"})
})

When it happens

Trigger: A request to a route like /hello/{name:alphabetical} where the segment contains digits, dashes, underscores, or other non-letter/space characters, e.g. /hello/john-doe or /hello/user123.

Common situations: URLs containing hyphenated names, slugs, numeric suffixes, or URL-encoded characters; users typing IDs where the route only allows letters and spaces.

Related errors

• empty parameter types
• ErrEmptyFormField
• ErrNotFound
• %s: invalid path part: dynamic path parameter and other para
• empty regex expression

AI-assisted analysis of kataras/iris@7bedaf55a0 (2026-08-30). Data as JSON: /api/errors/b854f638d6fbf45d. Report an issue: GitHub.