ChirpStack v3 to v4 Migration: What's Involved, What Goes Wrong, and When to Get Help

Why v3 networks need a plan now

ChirpStack v3 did its job well, and plenty of production LoRaWAN networks still run on it. But v3 is no longer actively developed. Every month you stay on it, you fall further behind on fixes and security updates, the documentation and community answers drift towards v4, and the people who know your setup get harder to find.

The good news: moving from v3 to v4 is a well-trodden path. The bad news: it is not an in-place upgrade. It is a migration to a different architecture, and it deserves to be treated like one.

What actually changes in v4

Before planning anything, it helps to understand why this is more than a version bump:

• One service instead of two. The separate v3 Network Server and Application Server are merged into a single ChirpStack service with one configuration file and per-region configuration files.
• Different data model. Organizations become tenants, service profiles and gateway profiles are gone, and device profiles take on more responsibility.
• New API. The v4 gRPC API is not compatible with v3. Anything that talks to the API — dashboards, provisioning scripts, billing jobs — needs to be checked and usually updated.
• Different integration payloads. Event messages sent over MQTT, HTTP and other integrations have a new structure. Downstream consumers that parse v3 payloads will break.
• New codec format. v4 codecs use the decodeUplink / encodeDownlink function format. v3-style Decode and Encode functions need converting and testing.
• Region-aware gateway topics. Gateway Bridge MQTT topics are prefixed per region in v4, so gateway connectivity needs reconfiguring as part of the move.

None of these are hard on their own. Together, they touch almost every part of a production network.

The migration at a high level

A typical v3 → v4 migration follows these stages:

1. Inventory. List every tenant, application, device profile, gateway, integration, codec and API consumer. Most surprises come from things nobody remembered existed.
2. Build the v4 environment. Install ChirpStack v4 alongside v3, with PostgreSQL (including the required pg_trgm extension), Redis, MQTT and Gateway Bridge configured for your regions.
3. Rehearse the data migration. The official chirpstack-v3-to-v4 migration tool reads your v3 databases and writes them into v4. Run it against a copy of production data first — never for the first time on the real thing.
4. Validate. Check device counts, keys, sessions, gateways and profiles. Convert codecs and test them with real payloads. Point a test copy of each integration at v4 and confirm the downstream systems still work.
5. Plan the cut-over. Agree a maintenance window, a step-by-step runbook, success criteria and — most importantly — a rollback plan that has been tested.
6. Cut over. Stop v3, run the final migration, repoint gateways, verify traffic and integrations, then monitor closely for the following days.

Five places migrations go wrong

These are the issues that turn a planned evening of work into a lost weekend:

1) Device sessions don't survive the move

If device session data is not migrated correctly, ABP devices stop being recognised and OTAA devices have to rejoin. On a large fleet — especially battery devices with long rejoin intervals — that can mean days of missing data.

2) Integrations break silently

v4 publishes events in a different structure. The network looks healthy, devices are reporting, and yet the dashboards, databases and alerting systems downstream quietly stop receiving usable data.

3) Codecs behave differently

A converted codec that looks right can still produce different output for edge cases: negative values, unusual fPorts, or payloads from older firmware versions. Test with real historic payloads, not just one happy-path example.

4) Gateways connect, but to the wrong place

Region prefixes, MQTT credentials and Gateway Bridge configuration all change. A gateway can show as connected to the broker while its events go to a topic that nothing subscribes to.

5) There's no real rollback

Many teams plan a rollback as "we'll switch back to v3". But once devices have rejoined v4 or frame counters have moved on, going back is not that simple. A rollback plan needs to be rehearsed, with a clear point of no return.

How long does it take?

For a small, simple network, a migration can be planned and completed in a few days. For production networks with thousands of devices, multiple tenants, custom integrations and strict uptime requirements, two to six weeks from inventory to cut-over is more realistic — most of it in preparation and testing, not the cut-over itself.

Should you do it yourself?

An in-house migration is a reasonable choice if you can answer "yes" to most of these:

• Someone on the team knows both your v3 setup and ChirpStack v4 well
• You have a staging environment where you can rehearse with production data
• You have a full list of integrations and API consumers, and their owners
• You can schedule a maintenance window and tolerate some device rejoins
• You have tested backups of your v3 databases and know how to restore them

If you answered "no" to two or more, the migration is still very doable — but it is worth getting experienced help for the planning, the rehearsal and the cut-over itself.

Getting help

We migrate ChirpStack v3 networks to v4 on customer infrastructure and our own, with a rehearsal on a copy of your data, a written cut-over runbook and a tested rollback plan. Not sure where to start? A ChirpStack health check is a good first step.

Talk to a ChirpStack engineer about your migration — the scoping call is free, and you get a written plan and fixed-price quote with no obligation.