"there is no unique or exclusion constraint matching the ON CONFLICT specification" error when Kong's binary is newer than its applied migrations

We are receiving the following error repeatedly throughout our Kong logs.

[error] 2035#0: *423 [lua] init.lua:49: flush_data(): error occurred during counters data flush: ERROR: there is no unique or exclusion constraint matching the ON CONFLICT specification, client: 12.123.123.124, server: kong_cluster_telemetry_listener

What does this error mean and how can we resolve it?

The error means that a running Kong node issued an INSERT ... ON CONFLICT (...) statement whose conflict columns don’t match any unique index that actually exists on the target table in the database. This happens whenever the Kong Gateway binary is newer than the migrations that have actually been applied to the database it’s connected to, so a column or index the binary expects isn’t there yet.

This is a general class of issue that can occur on any upgrade where migrations weren’t fully applied before starting the newer binary, not just one specific version pair. For example, on current Kong Gateway, the 3.12.0.0 migration changed the license_data table’s unique index (adding license_creation_date to it), so a 3.12.0.0-or-later binary connecting to a database that hasn’t had that migration applied hits exactly this error.

To fix this:

• If you’re not ready to complete the upgrade, restore a database backup that matches the Kong version you were previously running, and hold off starting the newer binary until you’re ready to migrate.
• If you are proceeding with the upgrade, run the pending migrations to completion against the database (kong migrations up, followed by kong migrations finish once all nodes are upgraded) before starting the newer Kong binary against it, so the schema matches what that binary expects.

Reference: Upgrade Kong Gateway