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 to the application, pass it to the install function in the specified module. The code snippets below show how to install StatusPages...

... inside the embeddedServer function call.
... inside the explicitly defined module, which is an extension function of the Application class.

                    import io.ktor.server.engine.*
                    import io.ktor.server.netty.*
                    import io.ktor.server.application.*
                    import io.ktor.server.plugins.statuspages.*

                    fun main() {
                        embeddedServer(Netty, port = 8080) {
                            install(StatusPages)
                            // ...
                        }.start(wait = true)
                    }
                

                    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: 02 April 2024