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:
TENANTTENANT_DATASYSTEM_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.
Identify the Forge Cloud ID for both the old and new installations.
Contact the engineering team to stash the existing tenant data associated with the
u_tenant_surrogate_idconflict.In the Jira administration page, navigate to Settings > Apps > Manage apps.
Locate BigGantt and click Install.
The application installs successfully once the database conflict is removed.