# Upgrading to Web UI 1.0

!!! tip "Version Compatibility Requirement"

    Karafka Web UI `1.0` requires Karafka `2.6` - these components must be upgraded together. Attempting to run Web UI `1.0` with older versions of Karafka will result in compatibility errors. Please ensure you upgrade both components as part of the same deployment process. Karafka `2.6` Upgrade Guide can be found [here](https://karafka.io/docs/Upgrades-Karafka-2.6.md).

Before upgrading to Karafka Web UI `1.0`, please review our [General Karafka Upgrade Guide](https://karafka.io/docs/Upgrades-Upgrading.md) first. This document provides essential advice on upgrading Karafka and its components and general best practices to ensure a smooth transition. The general guide contains fundamental steps that apply to all upgrades, while this specific guide focuses only on the changes introduced in the Web UI `1.0` release. Following both guides will help you navigate the upgrade process with minimal disruption to your production systems.

## Upgrading to Web UI 1.0 / Version Numbering Change

Web UI `1.0` is the direct successor to `0.11.x` - there are **no breaking changes** to configuration, the public API, or behavior between `0.11.7` and `1.0`. The version was promoted from `0.x` to `1.0` to reflect the long-standing production stability of the Web UI. No migration steps are required on account of the version number change alone.

Starting with Karafka `3.0`, Web UI versioning will align with Karafka's major version - both will release as `3.0` together and move in lockstep from that point forward.

## Upgrading to Web UI 1.0 / CSRF Protection Change

The CSRF protection mechanism has been replaced. The previous token-based approach (`route_csrf` plugin) has been removed in favour of header-based protection using the `Sec-Fetch-Site` header (`sec_fetch_site_csrf` plugin).

For most users this is transparent - all modern browsers automatically include the `Sec-Fetch-Site` header and the new approach requires no changes to your application.

If you have non-browser clients, custom HTTP clients, or integration tests that send requests directly to the Web UI without browser-standard headers, those clients will need to include the `Sec-Fetch-Site: same-origin` (or `same-site`) header. Requests lacking this header will be rejected as potential cross-site forgeries.

## Upgrading to Web UI 1.0 / Dynamic Worker Count in the UI

The Web UI now reads the live worker count from `Karafka::Server.workers.size` instead of the static `Karafka::App.config.concurrency` value. This means the UI accurately reflects runtime thread pool changes when dynamic worker pool scaling (introduced in Karafka `2.6`) is in use.

No configuration change is required. The display updates automatically.

## Upgrading to Web UI 1.0 / Poll Interval Monitoring

Consumer reporting now tracks `poll_interval` (`max.poll.interval.ms`) per subscription group alongside the existing `poll_age` metric. This gives you visibility into how close each subscription group is to its polling timeout, helping catch slow consumers before they are kicked out of the group.

The consumer schema has been bumped to **1.7.0** to carry this additional field.

## Upgrading to Web UI 1.0 / Deployment

Because of the consumer schema version bump to `1.7.0`, follow the standard zero-downtime upgrade procedure:

1. Make sure you have upgraded to `0.11.7` before and that it was fully deployed.
1. Test the upgrade on a staging or dev environment.
1. The Web UI interface may throw 500 errors during the upgrade because of schema incompatibility (until Puma is redeployed and all consumers are replaced). This will have no long-term effects and can be ignored.
1. `Karafka::Web::Errors::Processing::IncompatibleSchemaError` **is expected**. It is part of the Karafka Web UI zero-downtime deployment strategy. This error allows the Web UI materialization consumer to back off and wait for it to be replaced with a new one.
1. Perform a rolling deployment (or a regular one) and replace all consumer processes.
1. Update the Web UI Puma.
1. **No** CLI command execution is required.
1. Enjoy.


---

*Last modified: 2026-06-10 20:59:53*