kataras/iris · error · ErrNotFound

version %w

Error message

version %w

What it means

versioning.ErrNotFound wraps context.ErrNotFound and reports that a request's API version does not match any version the server has registered. It is a sentinel error used by the versioning matcher/handlers so callers can errors.Is-check it; the wrapped message surfaces as 'version not found'.

Source

Thrown at versioning/version.go:37

	AcceptHeaderKey = "Accept"
	// AcceptHeaderVersionValue is the Accept's header value search term the requested version.
	AcceptHeaderVersionValue = "version"
	// NotFound is the key that can be used inside a `Map` or inside `ctx.SetVersion(versioning.NotFound)`
	// to tell that a version wasn't found, therefore the `NotFoundHandler` should handle the request instead.
	NotFound = "iris.api.version.notfound"
	// Empty is just an empty string. Can be used as a key for a version alias
	// when the requested version of a resource was not even specified by the client.
	// The difference between NotFound and Empty is important when version aliases are registered:
	// - A NotFound cannot be registered as version alias, it
	//   means that the client sent a version with its request
	//   but that version was not implemented by the server.
	// - An Empty indicates that the client didn't send any version at all.
	Empty = ""
)

// ErrNotFound reports whether a requested version
// does not match with any of the server's implemented ones.
var ErrNotFound = fmt.Errorf("version %w", context.ErrNotFound)

// NotFoundHandler is the default version not found handler that
// is executed from `NewMatcher` when no version is registered as available to dispatch a resource.
var NotFoundHandler = func(ctx *context.Context) {
	// 303 is an option too,
	// end-dev has the chance to change that behavior by using the NotFound in the map:
	//
	// https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html
	/*
		10.5.2 501 Not Implemented

		The server does not support the functionality required to fulfill the request.
		This is the appropriate response when the server does not
		recognize the request method and is not capable of supporting it for any resource.
	*/

	ctx.StopWithPlainError(501, ErrNotFound)
}

View on GitHub (pinned to 7bedaf55a0)

Solutions

1. Register the requested version on the server via versioning.NewGroup(app, "version") for each supported version.
2. Fix the client to send a supported version string exactly as registered.
3. Configure a custom NotFound handler in the matcher map to negotiate/redirect to the closest supported version.
4. Remove client calls to deprecated versions and migrate to an active one.

Example fix

// before (server only registers v2)
api := versioning.NewGroup(app, "/api").Version("v2")
// after (client asks v1)
api.Version("v1")
api.Version("v2")

// client side: check the version is one the server advertises
const supported = ["v1", "v2"]
if !slices.Contains(supported, requestedVersion) {
    requestedVersion = "v2" // fallback
}

handler := versioning.NewMatcher(map[string]context.Handler{
    "v1": h1, "v2": h2,
})
// in tests:
if errors.Is(err, versioning.ErrNotFound) {
    log.Println("client version unsupported; negotiate fallback")
}

When it happens

Trigger: A client sends a version header/param (e.g. 'X-API-Version: v9') that is not among the versions registered in versioning.NewGroup / NewMatcher; Get/GetByID/Update/Delete resource flows also return it when no version constraint matches.

Common situations: Client requesting a version the backend never registered (v9 when only v1–v3 exist), version string typos ('1.0' vs 'v1'), or after the server removed support for an old version.

Related errors

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

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