kataras/iris · warning

parameter is not alphabetical

Error message

parameter is not alphabetical

What it means

ErrParamNotAlphabetical is a sentinel error fired when a path parameter evaluated by the 'alphabetical' macro contains anything other than upper/lowercase letters or spaces (regexp ^[a-zA-Z ]+$). It is wrapped with the offending value via fmt.Errorf("%s: %w", ...), so the actual failing text precedes it in the message.

Source

Thrown at macro/macros.go:379

				return !(paramValue < min || paramValue > max)
			}
		})

	// Bool or boolean as bool type
	// a string which is "1" or "t" or "T" or "TRUE" or "true" or "True"
	// 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 (-)

View on GitHub (pinned to 7bedaf55a0)

Solutions

1. Remove the offending characters client-side or encode/normalize the value.
2. Relax the macro: use {name:string} (any text) or a custom regexp macro like {slug:[a-zA-Z-]+}.
3. Add a separate route with a broader macro for the values you need to accept.

Example fix

// before
app.Get("/cities/{name:alphabetical}", h) // rejects 'new-york'

// after
app.Get("/cities/{name:regexp(^[a-zA-Z -]+$)}", h) // allows dashes

const isAlpha = (s: string) => /^[a-zA-Z ]+$/.test(s);
const url = isAlpha(name) ? `/users/${encodeURIComponent(name)}` : "/users";

function isAlphabetical(v: string): boolean {
  return /^[a-zA-Z ]+$/.test(v);
}

When it happens

Trigger: Route registered with {name:alphabetical} (or Alphabetical macro used in macros) and a request path contains digits, punctuation or unicode letters, e.g. '/users/renée' or '/users/john-1'.

Common situations: URLs containing hyphens (common in slugs), accents/unicode names, or numbers reach an alphabetical-only route; typical with usernames, city names or search terms in the path.

Related errors

• errors joined from param parser: strings.Join(p.errors, "\n"
• parameter is not a file
• parameter is not a valid weekday
• empty form
• no trailing path parameter found

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