kataras/iris · warning

parameter is not a file

Error message

parameter is not a file

What it means

ErrParamNotFile is fired when a parameter evaluated by the 'file' macro contains characters outside letters, digits, underscore, dash, dot (regexp ^[a-zA-Z0-9_.-]*$). It signals that the path segment does not look like a valid filename and is wrapped with the failing value.

Source

Thrown at macro/macros.go:391

			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
		}
		return paramValue, true
	})
	// Path type
	// anything, should be the last part
	//
	// It allows everything, we have String and Path as different

View on GitHub (pinned to 7bedaf55a0)

Solutions

1. URL-encode the filename properly on the client (spaces as %20 still decode to a space and will fail; rename the file instead).
2. Sanitize/rename the served file to letters, digits, dot, dash or underscore only.
3. Use a broader macro like {file:path} or {file:string} if arbitrary segments should be accepted.

Example fix

// before
app.Get("/files/{name:file}", h) // 'my report.pdf' fails

// after
// rename file to 'my_report.pdf' or use:
app.Get("/files/{name:path}", h)

const isFile = (s: string) => /^[a-zA-Z0-9_.-]*$/.test(s);
if (!isFile(filename)) filename = filename.replace(/[^a-zA-Z0-9_.-]/g, '_');

function isFileName(v: string): boolean {
  return /^[a-zA-Z0-9_.-]*$/.test(v);
}

When it happens

Trigger: Route such as app.HandleDir with a {file:file} path parameter, or any route using {p:file}, and the request segment contains slashes, spaces, or other special characters, e.g. '/files/my file.txt' or '/files/a/b'.

Common situations: Users requesting files with spaces in the name, URL-encoded or nested paths, or clients sending paths with query-like characters inside the segment.

Related errors

• errors joined from param parser: strings.Join(p.errors, "\n"
• parameter is not alphabetical
• 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/a9f911de71fc135f. Report an issue: GitHub.