How to Evaluate/Fix SQL Error: Duplicate Entry

SQL error: Duplicate entry '<generated_label>' for key 'catissue_specimen.OS_SPMN_LABEL_UQ'.
Please report this error to the system administrator. (COMMON_SQL_EXCEPTION)

What does this mean?

Every specimen label in OpenSpecimen must be unique (either within the collection protocol or across the whole system).

This error triggers when you try to save a sample with a label name that already exists. It is usually caused by:

A label format is too simple/non-unique and generating the same label twice
Accidentally typing the same label twice.
A duplicate label already active in the system.

Common Reasons & Examples

Reason Example token and details Label format with non-unique token - simple Eg: %PPI%_%SP_TYPE% - Using this, the user can't add two specimens with the same type. Fix: Add unique identifier - %PPI%_%SP_TYPE%_%PPI_UID(2)% %PPI%_%SP_TYPE%_%PPI_SPEC_TYPE_UID(2)% %PPI%_%SP_TYPE%_%SYS_UID(2)% Primary vs derived/aliquots tokens are non-unique Primary: %CP_CODE%_%PPI%_%VISIT_UID% Derived: %CP_CODE%_%PPI%_%PSPEC_UID% For both, it creates the same label format: To make it unique, add UID, or a character to make it unique Fix: Primary: %CP_CODE%_%PPI%_P%_%SP_TYPE%PPI_UID(2)% Derived: %PSPEC_LABEL%_D%PSPEC_UID(2)% Manual Label: When user enters labels manually Check and verify the entered label either its added more than once on the data entry page or is already present in the system. Fix: Add a different label UID sequence counter is out of sync After legacy data import, bulk import, or specimen deletion, the internal counter for labels is lower than the actual number of specimens, causing it to generate a number that already exists. Fix: Reset/insert the last sequence used. Refer to this wiki page.

Tips to check for duplicate label

Verify if the label already exists in the system (using global search). If the label is not found, specimen creation may have failed due to a duplicate label. Review the CP and SR label formats to ensure unique labels are generated across all lineages. If not, fix them. Refer to this wiki for help. If label formats are correct, check if the UID sequence counter is out of sync and fix it. Refer to this wiki for details.