Ktor 2.1.1 Help

Status pages

The StatusPages plugin allows Ktor applications to respond appropriately to any failure state based on a thrown exception or status code.

Add dependencies

To use StatusPages, you need to include the ktor-server-status-pages artifact in the build script:

implementation("io.ktor:ktor-server-status-pages:$ktor_version")
implementation "io.ktor:ktor-server-status-pages:$ktor_version"
<dependency> <groupId>io.ktor</groupId> <artifactId>ktor-server-status-pages-jvm</artifactId> <version>${ktor_version}</version> </dependency>

Install StatusPages

To install the StatusPages plugin, pass it to the install function in the application initialization code. Depending on the way used to create a server, this can be the embeddedServer function call ...

import io.ktor.server.application.* import io.ktor.server.plugins.statuspages.* // ... fun main() { embeddedServer(Netty, port = 8080) { install(StatusPages) // ... }.start(wait = true) }

... or a specified module.

import io.ktor.server.application.* import io.ktor.server.plugins.statuspages.* // ... fun Application.module() { install(StatusPages) // ... }

Configure StatusPages

There are three main configuration options provided by the StatusPages plugin:

  • exceptions: configures a response based on mapped exception classes

  • status: configures a response to a status code value

  • statusFile: configures a file response from the classpath

Exceptions

The exception handler allows you to handle calls that result in a Throwable exception. In the most basic case, the 500 HTTP status code can be configured for any exception:

install(StatusPages) { exception<Throwable> { call, cause -> call.respondText(text = "500: $cause" , status = HttpStatusCode.InternalServerError) } }

You can also check specific exceptions and respond with the required content:

install(StatusPages) { exception<Throwable> { call, cause -> if(cause is AuthorizationException) { call.respondText(text = "403: $cause" , status = HttpStatusCode.Forbidden) } else { call.respondText(text = "500: $cause" , status = HttpStatusCode.InternalServerError) } } }

Status

The status handler provides the capability to respond with specific content based on the status code. The example below shows how to respond on requests if the resource is missing on a server (the 404 status code):

install(StatusPages) { status(HttpStatusCode.NotFound) { call, status -> call.respondText(text = "404: Page Not Found", status = status) } }

Status file

The statusFile handler allows you to serve HTML pages based on the status code. Suppose your project contains the error401.html and error402.html HTML pages in the resources folder. In this case, you can handle the 401 and 402 status codes using statusFile as follows:

install(StatusPages) { statusFile(HttpStatusCode.Unauthorized, HttpStatusCode.PaymentRequired, filePattern = "error#.html") }

The statusFile handler replaces any # character with the value of the status code within the list of configured statuses.

Last modified: 21 September 2022