Resolving u_tenant_surrogate_id Unique Constraint Violation During BigGantt Forge Installation

Resolving u_tenant_surrogate_id Unique Constraint Violation During BigGantt Forge Installation

This article explains how to resolve the u_tenant_surrogate_id unique constraint violation that occurs during BigGantt Forge application installation or migration.

Summary

When you install or reinstall the BigGantt Forge application, the process may fail with a duplicate key error. This issue occurs when the database retains records from a previous installation, creating a conflict with the new installation attempt.

Symptoms

The installation fails, and the following error appears in the system logs:

Caused by: java.sql.BatchUpdateException: Batch entry 0 insert into "TENANT" ("CHANGE_TS", "TYPE", "SURROGATE_ID", "ID") values (('2026-06-22 06:19:47.116+00'), ('JiraCloud'), ('https://example.atlassian.net'), ('201583'::int4)) was aborted: ERROR: duplicate key value violates unique constraint "u_tenant_surrogate_id" Detail: Key ("SURROGATE_ID")=(https://example.atlassian.net) already exists.

Cause

The system receives an installation event on the /jiracloud/forge-installed endpoint. However, the database still contains data associated with the Jira Cloud URL from a previous installation. Specifically, records remain in the following tables:

  • TENANT

  • TENANT_DATA

  • SYSTEM_INSTALLATION

Because the SURROGATE_ID (the Jira Cloud URL) must be unique, the database blocks the insertion of the new record.

Resolution

To resolve this conflict, the engineering team must clear the legacy data to allow the new Forge Cloud ID to register.

  1. Identify the Forge Cloud ID for both the old and new installations.

  2. Contact the engineering team to stash the existing tenant data associated with the u_tenant_surrogate_id conflict.

  3. In the Jira administration page, navigate to Settings > Apps > Manage apps.

  4. Locate BigGantt and click Install.

The application installs successfully once the database conflict is removed.