Frequently asked, honestly answered

What Go version does Iris v14 need?

Go 1.27 or newer. That is what go.mod declares and what continuous integration builds against. Version 14 uses Go 1.27's generic methods in its public API and the standard library's encoding/json/v2 for every request and response, so it cannot be compiled by an older toolchain.

How do I install it?

Run go get github.com/kataras/iris/v14@latest inside a module. The import path is github.com/kataras/iris/v14, with the major version suffix, which is how Go modules work and is not optional.

Is Iris free, and what is the licence?

Yes. The framework is BSD-3-Clause licensed, the same licence the Go project itself uses. The book is free as well, as a PDF and to read online. There is no paid tier, no licence key and no commercial edition.

Where is the API reference?

Two places, for two different questions. pkg.go.dev has every exported symbol and its signature. Google's Code Wiki at https://codewiki.google/github.com/kataras/iris is generated from the repository and regenerated commit by commit, and answers questions about the codebase in prose, with a chat grounded in the actual source. The book on this site covers the third question neither of them does, which is why the framework is shaped the way it is.

I have a v12 application. How hard is the upgrade?

Mostly mechanical, and the compiler finds nearly all of it. The import path gains a /v14 suffix, several Context methods were renamed, and some packages moved. Chapter 23 of the book is the tour and MIGRATION.md in the repository is the substitution list. The renames are the bulk of the work: for example Context.GetHeader is gone, and request headers are now ctx.Header while response headers are ctx.ResponseHeader.

Does Iris use net/http or fasthttp?

net/http. An Iris application is an http.Handler once it is built, which is why it composes with standard-library middleware, with httptest, and with the rest of the Go ecosystem without adapters.

Do I have to use iris.NewBuilder?

No. iris.New gives you an application you configure yourself, and everything in the book works with either. The builder exists because most production applications need the same eight or nine things wired in the same order, and getting that order wrong is the kind of mistake that is invisible until it matters. With the builder it does not compile.

How do I send a JSON response and handle the error in one line?

Hand the value and the error your service returned to one of the context helpers: ctx.OK(value, err) for a 200, ctx.Created(value, err) for a 201 that wraps a bare id as {"id": ...}, ctx.NoContent(modified, err) for a 204 or a 304, ctx.List(items, err) for a JSON array that is [] and never null, ctx.Count(n, err) for {"count": N} and ctx.Paginated(collect) for a page envelope. A non-nil error goes through the central mapping in rest/errors and the helper returns false, so the handler never branches on it. There is no rest root package in v14; these are methods on the context itself.

How many middleware packages are included?

31, all in-tree, so they are versioned and tested with the framework rather than pinned separately in your go.mod. They cover access logging, authentication, caching, compression, CORS, rate limiting, recovery, sessions, request IDs, websockets and more.

How do I authenticate a service, a cron job or a webhook sender?

With middleware/apikey, not a hand-written header check. apikey.New(apikey.Options{Keys: ...}) reads the key from Authorization: Bearer by default, or from a custom header such as X-API-Key with Scheme: apikey.NoScheme, and compares it against every configured key in constant time with no early exit. Keys maps a principal name to its secret, one per consumer, so a leak is traceable and one key can be revoked without breaking the rest; apikey.Get(ctx) returns the principal that matched, and ctx.User() sees it too. Hash: apikey.SHA256 lets the configuration hold digests instead of usable credentials, and Lookup resolves keys that live in a database, where a store that is down is a 500 rather than a 401. The default is to deny: no keys and no Lookup rejects every request and logs a warning.

Are there runnable examples?

Yes, 78 of them in the repository under _examples, each its own directory with a main.go you can run directly. The book's chapter 22 also builds two complete applications file by file.

Does Iris support Server-Sent Events?

Yes, as a first-class transport rather than something you assemble. github.com/kataras/iris/v14/sse writes a stream and reads somebody else's. sse.Open writes nothing, so the protocol headers commit on the first Send and an authorization check that fails after Open still returns an ordinary status code. It carries a 15s heartbeat, automatic event ids, a terminal frame written on success as well as on failure so a client can detect truncation, and batching for text deltas.

How do I stream an LLM response in Go?

With github.com/kataras/iris/v14/ai, which renders and relays model streams over HTTP. It is provider-agnostic and ships no vendor SDK: you call whatever model you like and send the pieces as neutral parts, in 7 kinds covering text, reasoning, tool calls, tool results, usage, errors and a passthrough. The package handles the transport, the batching, the accounting hook and the failure classification. Chapter 21 of the book builds a gateway end to end.

Why does my SSE endpoint only send everything at the end?

Something in the chain is buffering the response, and in Iris there were two candidates. The compression middleware writes into a compressor, and the response recorder that accesslog installs, which iris.NewBuilder().LogRequests(true) turns on, writes into a bytes.Buffer. The recorder used to forward its buffer only when the handler had set Transfer-Encoding: chunked, which no SSE handler does, so the events piled up until the handler returned. That is fixed: the recorder steps aside for a streaming media type, and the first sse.Send removes every buffering wrapper for that response. Outside the framework the usual causes are a reverse proxy buffering, which the no-cache, no-transform and X-Accel-Buffering headers address, and Timeout.HandlerTimeout, which makes streaming impossible because its response writer cannot flush.

Can one handler serve both streaming and non-streaming AI requests?

Yes, and that is the point of ai.Open. When the request asks to stream, each part goes out as it is produced. When it does not, the parts are assembled and written as one JSON document. Nothing in the handler between Open and Close changes. Options.Stream is a pointer to a bool rather than a bool so that nil stays distinguishable from false, in which case the shape is negotiated on the Accept header.

Does this website track me?

No. There is no analytics, no tracking pixel, no advertising, and no cookie set by this site. The sponsors page deliberately loads no avatars, because 379 avatar requests would hand a third party the IP address of everyone who opened it.

Does Iris ship an HTTP client for calling other services?

Yes. github.com/kataras/iris/v14/client is the outbound half: a base URL, persistent request options, retries with exponential backoff, a rate limit per client or per endpoint, and redaction of API keys from error messages and debug dumps are all options you pass once. Responses bind to a type named at the call site, c.BindJSON[Order](ctx, method, path, nil), the same shape the server side uses. A failed status comes back as an APIError that the rest/errors package can forward to your own caller. The package is a thin layer over github.com/kataras/httpclient, the author's standalone client, with the framework's JSON policy as its default, so an application imports only the Iris package.

How is the project funded?

GitHub Sponsors, and nothing else. The book used to cost money and no longer does. Everyone who has sponsored is listed by name on the sponsors page, without amounts.

Where do I report a security problem?

Not in the public issue tracker. SECURITY.md in the repository has the disclosure process and the address to use.

Something missing? Ask in Discussions. Questions that keep coming back end up on this page.