> For the complete documentation index, see [llms.txt](https://docs.roadrunner.dev/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roadrunner.dev/docs/general/v3-migration.md).

# Upgrade from v2025 to v3

This guide lists the major upgrade steps from RoadRunner v2025 with v5 plugins to RoadRunner v3 with v6 plugins. The linked reference pages contain the configuration examples and full behavior descriptions. See the [v3 release notes](/docs/releases/v3-0-0.md) for new features.

Keep `version: "3"` at the root of `.rr.yaml`. Source builds require Go 1.27 or later.

## Application and Configuration Changes

| Area                  | Upgrade action                                                                                                                                                                                                                                                                |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| HTTP middleware       | Requests enter middleware from left to right. Reverse an existing v5 list to keep its execution order. See [Middleware order](/docs/http/http.md#middleware-order).                                                                                                           |
| HTTP/2                | Use HTTP/2 prior knowledge for cleartext connections. HTTP/1.1 `Upgrade: h2c` is no longer supported. See [HTTP/2](/docs/http/http.md#http2).                                                                                                                                 |
| AMQP                  | Move broker settings to named connections. Set `config.connection` for each pipeline. Move exchange and queue settings into their nested sections and remove AMQP `config.version`. See [RabbitMQ](/docs/queues-and-jobs/amqp.md).                                            |
| Logging               | Replace `file_logger_options` with `output`. Use an external tool for log rotation. Update JSON parsers for `time` and uppercase levels. Output is asynchronous; a full queue drops new records. See [Logger](/docs/logging-and-observability/logger.md).                     |
| Tracing               | Replace the removed Zipkin exporter with OTLP. Use the server span to measure request latency; middleware spans end before the next handler starts. See [OpenTelemetry](/docs/logging-and-observability/otel.md).                                                             |
| RPC                   | Replace MessagePack with a supported codec. Goridge v4 supports JSON, protobuf, Gob, and raw payloads. See [RPC](/docs/php-worker/rpc.md).                                                                                                                                    |
| Jobs                  | Reserve the `pool` job header for named-pool routing. Configure either `jobs.pool` or `jobs.pools`. The default `pipeline_size` is `100000`. Set `pipeline_size: 1000000` to keep the v5 limit. See [Jobs](/docs/queues-and-jobs/overview-queues.md).                         |
| NATS                  | Review stream retention and repeated-job handling. Stopping a pipeline now preserves messages unless stream deletion is enabled. A new consumer can receive retained messages again after restart. See [NATS retention](/docs/queues-and-jobs/nats.md#delete-stream-on-stop). |
| Centrifuge            | Remove calls to `centrifuge.RateLimit`. Update direct clients for the supported DTOs and events. See [Centrifuge](/docs/plugins/centrifuge.md).                                                                                                                               |
| Environment files     | A root `envfile` is loaded without experimental mode. Supply the configured file or remove the setting. See [Environment](/docs/php-worker/environment.md).                                                                                                                   |
| Server initialization | Values in `server.on_init.env` override inherited environment values. Use a command sequence for arguments that contain spaces. See [Server](/docs/plugins/server.md).                                                                                                        |
| Metrics               | Update Jobs dashboards for counter types and separate requeue totals. See [Metrics](/docs/logging-and-observability/metrics.md).                                                                                                                                              |
| TCP plugin            | RoadRunner v3 does not support the TCP plugin. Applications that use the `tcp:` plugin stay on RoadRunner v2025. This does not affect `tcp://` transport for RPC or worker relays. See [TCP](/docs/plugins/tcp.md).                                                           |

## Custom Go Plugins

* Update RoadRunner library imports to `github.com/roadrunner-server/roadrunner/v3`.
* Replace imports from `api/v4` with generated bindings from `api-go/v6` or contracts from `api-plugins/v6`. The `api` repository contains protobuf schemas.
* Update plugin loggers to `*slog.Logger` and use the context-aware Jobs and KV contracts.
* Update worker pool imports to `pool/v2` and Goridge imports to `goridge/v4`.
* Update custom builds to the Velox v3 module configuration.

See [Writing a Plugin](/docs/customization/plugin.md), [Writing a Jobs Driver](/docs/customization/jobs-driver.md), and [Building RR with a Custom Plugin](/docs/customization/build.md) for imports, signatures, and build examples.