This book documents Iris v14 (github.com/kataras/iris/v14) exclusively.
Every chapter describes the current API with no comparisons to earlier
releases, so there is nothing in these pages to translate or un-learn. This
chapter exists for one audience: readers bringing an existing v12 codebase
forward. It tells you where the migration instructions live and how to
approach the upgrade. It deliberately does not duplicate the instructions
themselves.
Background
In semantic versioning (the MAJOR.MINOR.PATCH numbering Go modules
follow), a major version upgrade is the one release type allowed to
break existing code: names may be removed, defaults may change, and your
program may need edits before it compiles again. Breaking changes are not
carelessness; they are how a framework sheds accumulated mistakes and
unsafe defaults without carrying them forever: v14’s secure-by-default
behavior exists precisely because a major release was the one moment it
could change. Go makes the break explicit by putting the major version in
the import path (/v12, /v14), so the two versions cannot be confused
inside one build.
The Canonical Migration Guide
The step-by-step migration guide ships with the framework repository and is maintained alongside the code:
https://github.com/kataras/iris/blob/main/MIGRATION.md
Because it lives next to the source, it (not this book) is the authority on what changed between v12 and v14. Read it end to end before touching your code. The guide covers these categories, each with the exact replacement and a code sample:
| Category | What it covers |
|---|---|
| Import path | The module major version moves from /v12 to /v14; a one-shot sed rewrite for go.mod and every source file. |
| Package relocations | sessions, cache, websocket, i18n, view and versioning move under middleware/; middleware/recover becomes middleware/recovery, mvc becomes controller/mvc, macro becomes core/router/macro, x/client becomes client, x/jsonx becomes rest/types, x/errors becomes rest/errors. middleware/logger, hero and x/sqlx are removed outright. Four moved packages also changed their entry point (cache, recovery, websocket, view). |
| Removed v12 APIs | Each removed name with its single v14 replacement: Party → Router, PartyConfigure/Configure → Router/Routing, Done/DoneGlobal/UseGlobal → the Use family, OnErrorCode → HandleNoRoute/HandleNoMethod plus rest/errors, iris.Configuration → iris.Options, RegisterView/ctx.View → middleware/view, iris.Addr/iris.TLS/iris.AutoTLS/Runner → app.Run(iris.ServerOptions{...}), SetContextErrorHandler → the ContextOptions.ErrorHandler option, HandleDir/Favicon → controller/fileserver, WWW/SubdomainRedirect → middleware/rewrite, app.Validator → ContextOptions.RequestValidator, hero → the built-in DI container, mvc.GRPC → controller/mvc.GRPC, Dependencies() → DI(). |
| Context method changes | The largest mechanical part: all eighteen URLParam* methods become ctx.Query().Get*; ctx.Params().Get becomes GetString; request and response accessors split by name, so ctx.GetHeader(k) becomes ctx.Header(k) and the v12 two-argument ctx.Header(k, v) setter becomes ctx.SetHeader(k, v) (with ResponseHeader new for reading back what a handler set); the same split applies to content type. Plus the rename table (GetCookie → CookieValue, GetBody → Body, …), the removed methods (CallFunc, ReflectValue, …) and the new SetLogoutFunc/Logout signatures. |
| Corrected v12 behavior | Two v12 bugs whose fixes change runtime behavior without needing a code change: ReadBody with a *string/*[]byte target no longer re-reads a drained body, and KitchenTime.Scan no longer drops the minutes of a database TIME value. |
| Secure-by-default changes | Session cookies ship Secure with SameSite=Lax (and the sessions.Database interface is redesigned around generics); JWT verification reads the Authorization header only, dropping the v12 ?token= extractor; CORS no longer advertises credentials alongside a wildcard origin; AddCookie defaults to SameSite=Lax. |
| Opt-in hardening | New v14 capabilities that are off by default: ContextOptions.BodyMaxMemory request-body caps, session.RegenerateID after sign-in, fileserver.BlockHidden for static servers, requestid.ServerOnlyGenerator, a raised password.Cost. |
One path-parameter change is easy to miss because most code keeps
compiling. In v12 a {id:uuid} parameter stored the text it validated;
in v14 it stores a parsed uuid.UUID. Read it with
ctx.Params().GetUUID("id") or ctx.BindParam[uuid.UUID]("id").
ctx.Params().GetString("id") still works and returns the canonical
lowercase form, while ctx.BindParam[string]("id") on such a route
now answers 400.
Tips for a Smooth Upgrade
- Read the guide first, code second. Skim all of MIGRATION.md before editing anything, and note which categories your application actually touches. Most codebases hit the import path, one or two removed APIs and one behavior change. Knowing which ones up front turns the upgrade from exploration into execution.
- Upgrade in one commit on a dedicated branch. The import-path change touches every Go file, so there is no useful halfway state. Do the mechanical rewrite, apply the API replacements, and land the whole move as a single reviewable change.
- Let the compiler drive. The removed v12 names fail loudly: the renames were designed so that every stale call site becomes a compile error rather than code that silently misbehaves. Work through the error list with the guide’s replacement table beside you; when the build is green, the mechanical part of the migration is done.
- Run your test suite before shipping. The secure-by-default changes (session cookie attributes, JWT extraction, CORS credentials) and the two corrected v12 bugs compile without complaint but behave differently at runtime. Your integration tests are where those differences surface; see Chapter 16 if you need to add coverage first.
Starting Fresh
If you are not carrying v12 code, skip the migration guide entirely. New
projects should start from Chapter 1 or the
framework’s TUTORIAL.md,
both of which build directly on
the recommended v14 stack: iris.NewBuilder, dependency-injected services,
controllers with Routing(r iris.Router) methods and the response helpers.
There is no v12 heritage in that path and nothing to migrate away from.
Summary
- This book covers v14 only; upgrades from v12 are documented in the maintained guide at https://github.com/kataras/iris/blob/main/MIGRATION.md.
- The guide covers the import path move, package relocations, removed v12
APIs with their replacements, the
Contextmethod changes, corrected v12 behavior, secure-by-default changes and recommended opt-in hardening. - Upgrade deliberately: read the guide first, land the change in one commit, let compile errors guide the API replacements, and rely on your test suite to catch the behavior changes that compile cleanly.
- Fresh projects have nothing to migrate. Start at Chapter 1.
Further Reading
- MIGRATION.md: the maintained, authoritative v12-to-v14 migration guide this chapter points at.
- Semantic Versioning: the
MAJOR.MINOR.PATCHcontract and what each part promises about compatibility. - Go Modules: Developing a major version update:
why the major version appears in the import path and how
/v14releases work.