What the agent does
The agent reads the routes before it touches them, because error handling is only right if it knows what each one throws. In a service laid out like the postgres sample in ktorio/ktor-samples, build.gradle.kts applies the Ktor plugin 3.6.1 on Kotlin 2.4.20 with content negotiation, kotlinx JSON, Netty, logback, the YAML config module and the PostgreSQL driver, lists ktor-server-test-host-jvm and kotlin-test-junit as test dependencies, and has no src/test directory. PostgresApplication.kt installs serialization and routing, and connectToPostgres reads the user, password and database from postgres.yaml, the same file docker-compose.yaml extends to start the database.
plugins/Routing.kt wraps each of the four /articles routes in its own try: DbElementInsertException on create answers an empty 500, DbElementNotFoundException on read answers an empty 404, and an IllegalArgumentException from a missing or non-numeric id answers an empty 400 on read, update and delete. Two things fall through. ArticleService.update and delete return the row count from executeUpdate and never throw, so a PUT or DELETE for an id that does not exist answers 200. And both custom exceptions extend Throwable rather than Exception, so any handler written for Exception would miss them, which the agent notes before writing one.
The change adds ktor-server-status-pages-jvm to the dependencies and a plugins/StatusPages.kt with configureStatusPages(), called from the application module: exception<DbElementNotFoundException> answers 404, DbElementInsertException 500, IllegalArgumentException 400, Ktor's BadRequestException 400 for a body call.receive<Article>() cannot parse, and a last Throwable handler that logs through call.application.log and answers 500 with a generic message so no stack trace reaches a client; a status(HttpStatusCode.NotFound) block gives an unknown path a body too. Every answer is a serializable ErrorResponse(code, message) in models/, sent through the content negotiation already installed. Routing.kt loses its try blocks, and update and delete throw DbElementNotFoundException when the service reports zero rows.
The sandbox has no Docker, so the agent installs PostgreSQL from apt, starts it, and creates the articles database with the user and password from postgres.yaml, then runs the service with ./gradlew run and sends the failing requests with curl: a missing id, a non-numeric id, malformed JSON, an update of an id that does not exist, and an unknown path, reading each status and body. It also writes src/test/kotlin/com/example/StatusPagesTest.kt on testApplication, installing the plugin with a route that throws each exception, so the mapping is checked without a database, and runs ./gradlew test, the task build-all.sh runs for every sample in CI.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add StatusPages error handling to this Ktor service. Read build.gradle.kts, every file under src/main, postgres.yaml and docker-compose.yaml first. Add the ktor-server-status-pages dependency and a plugins/StatusPages.kt that maps DbElementNotFoundException to 404, DbElementInsertException to 500, IllegalArgumentException and Ktor's BadRequestException to 400, and any other Throwable to a logged 500 with a generic message, each answered as a serializable ErrorResponse with a code and a message through the installed content negotiation, plus a body for an unmatched route. Remove the try blocks from Routing.kt, and make update and delete answer 404 when the service reports zero rows. Note that the custom exceptions extend Throwable, not Exception. In the sandbox, install PostgreSQL from apt, create the database, user and password postgres.yaml names, run the service and send the failing requests with curl; also write a testApplication test that covers each mapping without a database and run ./gradlew test. Open a pull request whose description quotes the curl transcript and the test output and names the responses that changed.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
What comes back is a pull request that changes build.gradle.kts, PostgresApplication.kt and Routing.kt, adds plugins/StatusPages.kt, models/ErrorResponse.kt and the test file, and leaves ArticleService.kt, the config and the Compose files alone. The description quotes the curl transcript with each status and JSON body, the ./gradlew test output, and a short list of responses that changed: 404 and 500 now carry a body, malformed JSON answers 400, and an update or delete of a missing id answers 404 where it answered 200.
The run's record keeps the PostgreSQL install and the ./gradlew run log, every request the agent sent with its answer, and the test run, so a reviewer can see the behaviour against a real server before checking out the branch.
Before merging, a reviewer decides whether any client depends on the old 200 from PUT and DELETE on a missing id, reads the generic message the Throwable handler returns, and checks that the log line carries the exception the client no longer sees.
Run it on every Linear issue labelled `agent`
A team that tracks API cleanup in Linear starts the work from the issue. An automation with a linear trigger on linear.issue.labeled and agent in config.labels starts a run for each issue that gains the label; the trigger adds the issue after the automation's prompt, which asks the agent to read the issue, make the change it describes in the named service, and open a pull request that links back to the issue, so the prompt itself names no service and no exception.
Each run reads the issue it was given and the repository the Project holds, installs what the service needs in its own sandbox, and leaves a pull request with its own transcript in the record. An issue that asks for a different mapping, say a 409 on a duplicate insert, gets that mapping, because the run reads the issue rather than a template.
The use case this job follows, with its automation and trigger: Turn a Linear label into a PR.
Why run it on Rush?
Error handling written without running the service gets the edges wrong: a handler on Exception that never sees an exception extending Throwable, a malformed body that still answers 500, or a route that quietly answers 200 for a row that was never there. In a Rush sandbox the agent installs the real database, runs the real server and sends the real bad requests, and reads each answer before it writes the mapping.
The curl transcript and the test run stay with the pull request, so the reviewer reads what the API answers rather than what the diff suggests. The same job across a team's services runs in parallel, each with its own machine, its own database and its own pull request.
Frequently asked questions
Why does it matter that the exceptions extend Throwable?
Because a StatusPages handler is matched by type. exception<Exception> would never see DbElementNotFoundException or DbElementInsertException, which extend Throwable directly, and they would reach the catch-all instead. The agent registers each class explicitly and keeps a Throwable handler last.
Does this change what existing clients see?
Yes, in three places the pull request names: 404 and 500 answers gain a JSON body, a body the server cannot parse answers 400 instead of whatever the default pipeline produced, and PUT or DELETE on a missing id answers 404 rather than 200. A client that reads only the status is unaffected by the first; the reviewer decides on the third.
Can it run the service without Docker?
Yes. The sample starts PostgreSQL with Docker Compose, but the sandbox has no Docker, so the agent installs PostgreSQL from apt and creates the database, user and password postgres.yaml names. The service connects to localhost:5432 either way.
Will stack traces leak to clients?
No. The last handler logs the throwable through the application logger and answers a fixed message, so the detail goes to the server log, which logback.xml already configures, and the client gets a status and a code.
Is there a test that does not need the database?
Yes. The testApplication test installs the plugin with a route per exception and asserts the status and body for each, using the test host dependency the build already declares, so ./gradlew test checks the mapping on any machine.
More Ktor jobs
The same job on other stacks
- Add API Error Handling to an Express and Sequelize App (Sequelize)
- Add LLM API Error Handling to a Streamlit App (Streamlit)
- Add Global Error Handling to TanStack Query (TanStack Query)