Display a CTA to view the existing duplicate when adding a duplicate email/domain. (#16483)

Closes [89](https://github.com/twentyhq/core-team-issues/issues/89) ## Problem When users attempt to create or update a record with a duplicate value for a unique field (e.g., duplicate email or domain name), they receive a generic error message: "This record already exists. Please check your data and try again." This provides no actionable way to locate and view the existing conflicting record, forcing users to manually search for it. ## Solution This PR enhances duplicate key constraint error handling to automatically detect the conflicting record and display a "View existing record" link in the error notification. When clicked, users are navigated directly to the existing record's detail page. ## Backend Changes ### 1. PostgreSQL Error Parsing (`parse-postgres-constraint-error.util.ts`) - Extracts structured information from PostgreSQL `QueryFailedError` messages. ### 2. Conflicting Record Lookup (`find-conflicting-record.util.ts`) - Queries the database to find the existing record with the conflicting value ### 3. Error Handling Orchestration (`handle-duplicate-key-error.util.ts`) - Parses PostgreSQL error to extract column name and conflicting value - Attempts to find the conflicting record - Enriches `TwentyORMException` with `conflictingRecordId` and `conflictingObjectNameSingular` if found ### 4. Exception Computation Updates (`compute-twenty-orm-exception.ts`) - Made function `async` and added optional `entityManager` and `internalContext` parameters - Needed to support async database queries for conflicting record lookup ### 5. GraphQL Error Handler (`twenty-orm-graphql-api-exception-handler.util.ts`) - **Changes**: Enhanced `DUPLICATE_ENTRY_DETECTED` case to include `conflictingRecordId` and `conflictingObjectNameSingular` in GraphQL error extensions ## Frontend Changes ### 1. Error Extraction Utility (`get-conflicting-record-from-apollo-error.util.ts`) - Accesses GraphQL error extensions - Validates that both `conflictingRecordId` and `conflictingObjectNameSingular` exist and are strings - Returns `null` if validation fails ### 2. SnackBar Enhancement (`useSnackBar.ts`) - Extracts conflicting record info from Apollo error - Constructs URL using `getAppPath` utility - Adds link object to snackbar options with text "View existing record" <img width="931" height="858" alt="image" src="https://github.com/user-attachments/assets/28137dc7-18ab-4ffe-b669-1f2d4ec264d1" />
2025-12-16 18:27:34 +05:00
parent 75bba5a8ee
commit d998e3b92c
16 changed files with 335 additions and 41 deletions
@@ -30,10 +30,9 @@ export type SnackBarProps = Pick<ComponentPropsWithoutRef<'div'>, 'id'> & {
  duration?: number;
  icon?: ReactNode;
  message: string;
-  link?: {
-    href: string;
-    text: string;
-  };
+  actionText?: string;
+  actionOnClick?: () => void;
+  actionTo?: string;
  detailedMessage?: string;
  onCancel?: () => void;
  onClose?: () => void;
@@ -118,6 +117,10 @@ const StyledLink = styled(Link)`
  }
 `;

+const StyledActionButton = styled.div`
+  padding-left: ${({ theme }) => theme.spacing(6)};
+`;
+
 const defaultAriaLabelByVariant: Record<SnackBarVariant, string> = {
  [SnackBarVariant.Default]: 'Alert',
  [SnackBarVariant.Error]: 'Error',
@@ -134,7 +137,9 @@ export const SnackBar = ({
  id,
  message,
  detailedMessage,
-  link,
+  actionText,
+  actionOnClick,
+  actionTo,
  onCancel,
  onClose,
  role = 'status',
@@ -230,7 +235,14 @@ export const SnackBar = ({
      {isDefined(sanitizedDetailedMessage) && (
        <StyledDescription>{sanitizedDetailedMessage}</StyledDescription>
      )}
-      {link && <StyledLink to={link.href}>{link.text}</StyledLink>}
+      {actionText && actionTo && (
+        <StyledLink to={actionTo}>{actionText}</StyledLink>
+      )}
+      {actionText && actionOnClick && !actionTo && (
+        <StyledActionButton>
+          <LightButton title={actionText} onClick={actionOnClick} />
+        </StyledActionButton>
+      )}
    </StyledContainer>
  );
 };
@@ -58,7 +58,9 @@ export const SnackBarProvider = ({ children }: React.PropsWithChildren) => {
              message,
              detailedMessage,
              variant,
-              link,
+              actionText,
+              actionOnClick,
+              actionTo,
            }) => (
              <motion.div
                key={id}
@@ -76,7 +78,9 @@ export const SnackBarProvider = ({ children }: React.PropsWithChildren) => {
                    message,
                    detailedMessage,
                    variant,
-                    link,
+                    actionText,
+                    actionOnClick,
+                    actionTo,
                  }}
                  onClose={() => handleSnackBarClose(id)}
                />
@@ -8,6 +8,7 @@ import {
  snackBarInternalComponentState,
  type SnackBarOptions,
 } from '@/ui/feedback/snack-bar-manager/states/snackBarInternalComponentState';
+import { buildErrorAction } from '@/ui/feedback/snack-bar-manager/utils/build-error-action.util';
 import { useAvailableComponentInstanceIdOrThrow } from '@/ui/utilities/state/component-state/hooks/useAvailableComponentInstanceIdOrThrow';
 import { type ApolloError } from '@apollo/client';
 import { t } from '@lingui/core/macro';
@@ -143,9 +144,12 @@ export const useSnackBar = () => {
          ? getErrorMessageFromApolloError(apolloError)
          : t`An error occurred.`;

+      const errorAction = buildErrorAction(apolloError);
+
      setSnackBarQueue({
        id: uuidv4(),
        message: errorMessage,
+        ...errorAction,
        ...options,
        variant: SnackBarVariant.Error,
      });
@@ -0,0 +1,28 @@
+import { type ApolloError } from '@apollo/client';
+import { t } from '@lingui/core/macro';
+import { AppPath } from 'twenty-shared/types';
+import { getAppPath, isDefined } from 'twenty-shared/utils';
+import { getConflictingRecordFromApolloError } from '~/utils/get-conflicting-record-from-apollo-error.util';
+import { type SnackBarOptions } from '../states/snackBarInternalComponentState';
+
+export const buildErrorAction = (
+  apolloError?: ApolloError,
+): Pick<SnackBarOptions, 'actionText' | 'actionTo'> | null => {
+  if (!apolloError) {
+    return null;
+  }
+
+  const conflictingRecord = getConflictingRecordFromApolloError(apolloError);
+
+  if (isDefined(conflictingRecord)) {
+    return {
+      actionText: t`View existing record`,
+      actionTo: getAppPath(AppPath.RecordShowPage, {
+        objectNameSingular: conflictingRecord.conflictingObjectNameSingular,
+        objectRecordId: conflictingRecord.conflictingRecordId,
+      }),
+    };
+  }
+
+  return null;
+};
@@ -0,0 +1,35 @@
+import { type ApolloError } from '@apollo/client';
+import { isDefined } from 'twenty-shared/utils';
+
+export type ConflictingRecordInfo = {
+  conflictingRecordId: string;
+  conflictingObjectNameSingular: string;
+};
+
+export const getConflictingRecordFromApolloError = (
+  error: ApolloError,
+): ConflictingRecordInfo | null => {
+  const extensions = error.graphQLErrors?.[0]?.extensions;
+
+  if (!extensions) {
+    return null;
+  }
+
+  const conflictingRecordId = extensions.conflictingRecordId;
+  const conflictingObjectNameSingular =
+    extensions.conflictingObjectNameSingular;
+
+  if (
+    !isDefined(conflictingRecordId) ||
+    !isDefined(conflictingObjectNameSingular) ||
+    typeof conflictingRecordId !== 'string' ||
+    typeof conflictingObjectNameSingular !== 'string'
+  ) {
+    return null;
+  }
+
+  return {
+    conflictingRecordId,
+    conflictingObjectNameSingular,
+  };
+};
@@ -0,0 +1,76 @@
+import { compositeTypeDefinitions } from 'twenty-shared/types';
+import { capitalize } from 'twenty-shared/utils';
+
+import { type WorkspaceInternalContext } from 'src/engine/twenty-orm/interfaces/workspace-internal-context.interface';
+
+import { getFlatFieldsFromFlatObjectMetadata } from 'src/engine/api/graphql/workspace-schema-builder/utils/get-flat-fields-for-flat-object-metadata.util';
+import { type FlatObjectMetadata } from 'src/engine/metadata-modules/flat-object-metadata/types/flat-object-metadata.type';
+import { type WorkspaceEntityManager } from 'src/engine/twenty-orm/entity-manager/workspace-entity-manager';
+
+export const findConflictingRecord = async (
+  columnName: string,
+  conflictingValue: string,
+  objectMetadata: FlatObjectMetadata,
+  internalContext: WorkspaceInternalContext,
+  entityManager: WorkspaceEntityManager,
+): Promise<{ conflictingRecordId: string; fieldLabel: string } | null> => {
+  const flatFields = getFlatFieldsFromFlatObjectMetadata(
+    objectMetadata,
+    internalContext.flatFieldMetadataMaps,
+  );
+
+  const uniqueFields = flatFields.filter((field) => field.isUnique);
+
+  const matchingField = uniqueFields.find((field) => {
+    const compositeType = compositeTypeDefinitions.get(field.type);
+
+    if (!compositeType) {
+      return field.name === columnName;
+    }
+
+    const property = compositeType.properties.find(
+      (prop) => prop.isIncludedInUniqueConstraint,
+    );
+
+    if (!property) {
+      return false;
+    }
+
+    const expectedColumnName = `${field.name}${capitalize(property.name)}`;
+
+    return expectedColumnName === columnName;
+  });
+
+  if (!matchingField) {
+    return null;
+  }
+
+  const queryBuilder = entityManager.createQueryBuilder(
+    objectMetadata.nameSingular,
+    objectMetadata.nameSingular,
+    undefined,
+    {
+      shouldBypassPermissionChecks: true,
+    },
+  );
+
+  queryBuilder.where(`"${columnName}" = :value`, { value: conflictingValue });
+  queryBuilder.andWhere('"deletedAt" IS NULL');
+
+  try {
+    const conflictingRecord = await queryBuilder.getOne();
+
+    if (!conflictingRecord) {
+      return null;
+    }
+
+    return {
+      conflictingRecordId: conflictingRecord.id,
+      fieldLabel: matchingField.label,
+    };
+  } catch {
+    // If query fails (e.g., permission denied, record not found), return null
+    // This allows the duplicate error to still be shown without conflicting record link
+    return null;
+  }
+};
@@ -1,27 +1,68 @@
 import { msg } from '@lingui/core/macro';
-import { type QueryFailedError } from 'typeorm';
+
+import { type WorkspaceInternalContext } from 'src/engine/twenty-orm/interfaces/workspace-internal-context.interface';

 import { type FlatObjectMetadata } from 'src/engine/metadata-modules/flat-object-metadata/types/flat-object-metadata.type';
+import { type WorkspaceEntityManager } from 'src/engine/twenty-orm/entity-manager/workspace-entity-manager';
 import {
  TwentyORMException,
  TwentyORMExceptionCode,
 } from 'src/engine/twenty-orm/exceptions/twenty-orm.exception';

-interface PostgreSQLError extends QueryFailedError {
-  detail?: string;
+import { findConflictingRecord } from './find-conflicting-record.util';
+import {
+  parsePostgresConstraintError,
+  type PostgreSQLError,
+} from './parse-postgres-constraint-error.util';
+
+interface DuplicateKeyErrorWithMetadata extends TwentyORMException {
+  conflictingRecordId?: string;
+  conflictingObjectNameSingular?: string;
 }

-export const handleDuplicateKeyError = (
-  _error: PostgreSQLError,
-  _objectMetadata: FlatObjectMetadata,
-) => {
-  // Since we no longer have indexMetadatas in FlatObjectMetadata,
-  // we provide a generic error message
-  throw new TwentyORMException(
+export const handleDuplicateKeyError = async (
+  error: PostgreSQLError,
+  objectMetadata: FlatObjectMetadata,
+  internalContext: WorkspaceInternalContext,
+  entityManager: WorkspaceEntityManager,
+): Promise<DuplicateKeyErrorWithMetadata> => {
+  const parsedError = parsePostgresConstraintError(error);
+
+  if (!parsedError) {
+    return new TwentyORMException(
+      `A duplicate entry was detected`,
+      TwentyORMExceptionCode.DUPLICATE_ENTRY_DETECTED,
+      {
+        userFriendlyMessage: msg`This record already exists. Please check your data and try again.`,
+      },
+    );
+  }
+
+  const conflictingRecord = await findConflictingRecord(
+    parsedError.columnName,
+    parsedError.conflictingValue,
+    objectMetadata,
+    internalContext,
+    entityManager,
+  );
+
+  const fieldLabel = conflictingRecord?.fieldLabel;
+  const userFriendlyMessage = fieldLabel
+    ? msg`This ${fieldLabel} value is already in use. Please check your data and try again.`
+    : msg`This record already exists. Please check your data and try again.`;
+
+  const exception: DuplicateKeyErrorWithMetadata = new TwentyORMException(
    `A duplicate entry was detected`,
    TwentyORMExceptionCode.DUPLICATE_ENTRY_DETECTED,
    {
-      userFriendlyMessage: msg`This record already exists. Please check your data and try again.`,
+      userFriendlyMessage,
    },
  );
+
+  if (conflictingRecord) {
+    exception.conflictingRecordId = conflictingRecord.conflictingRecordId;
+    exception.conflictingObjectNameSingular = objectMetadata.nameSingular;
+  }
+
+  return exception;
 };
@@ -0,0 +1,37 @@
+import { type QueryFailedError } from 'typeorm';
+
+export type PostgreSQLError = QueryFailedError & {
+  detail?: string;
+  driverError?: Error & {
+    detail?: string;
+  };
+};
+
+export type ParsedConstraintError = {
+  columnName: string;
+  conflictingValue: string;
+};
+
+export const parsePostgresConstraintError = (
+  error: PostgreSQLError,
+): ParsedConstraintError | null => {
+  const errorDetail = error.detail;
+
+  if (!errorDetail) {
+    return null;
+  }
+
+  const detailMatch = errorDetail.match(/Key \(([^)]+)\)=\(([^)]+)\)/);
+
+  if (!detailMatch) {
+    return null;
+  }
+
+  const columnName = detailMatch[1].replace(/^["']|["']$/g, '');
+  const conflictingValue = detailMatch[2];
+
+  return {
+    columnName,
+    conflictingValue,
+  };
+};
@@ -1296,7 +1296,12 @@ export class WorkspaceEntityManager extends EntityManager {
        this.internalContext,
      );

-      throw computeTwentyORMException(error, objectMetadataItem);
+      throw await computeTwentyORMException(
+        error,
+        objectMetadataItem,
+        this,
+        this.internalContext,
+      );
    }
  }

@@ -2,10 +2,13 @@ import { msg } from '@lingui/core/macro';
 import { isDefined } from 'twenty-shared/utils';
 import { QueryFailedError } from 'typeorm';

+import { type WorkspaceInternalContext } from 'src/engine/twenty-orm/interfaces/workspace-internal-context.interface';
+
 import { POSTGRESQL_ERROR_CODES } from 'src/engine/api/graphql/workspace-query-runner/constants/postgres-error-codes.constants';
 import { handleDuplicateKeyError } from 'src/engine/api/graphql/workspace-query-runner/utils/handle-duplicate-key-error.util';
 import { PostgresException } from 'src/engine/api/graphql/workspace-query-runner/utils/postgres-exception';
 import { type FlatObjectMetadata } from 'src/engine/metadata-modules/flat-object-metadata/types/flat-object-metadata.type';
+import { type WorkspaceEntityManager } from 'src/engine/twenty-orm/entity-manager/workspace-entity-manager';
 import {
  TwentyORMException,
  TwentyORMExceptionCode,
@@ -15,10 +18,12 @@ interface QueryFailedErrorWithCode extends QueryFailedError {
  code?: string;
 }

-export const computeTwentyORMException = (
+export const computeTwentyORMException = async (
  error: Error,
  objectMetadata?: FlatObjectMetadata,
-) => {
+  entityManager?: WorkspaceEntityManager,
+  internalContext?: WorkspaceInternalContext,
+): Promise<Error | TwentyORMException> => {
  if (error instanceof QueryFailedError) {
    if (error.message.includes('Query read timeout')) {
      return new TwentyORMException(
@@ -34,9 +39,16 @@ export const computeTwentyORMException = (
      error.message.includes(
        'duplicate key value violates unique constraint',
      ) &&
-      isDefined(objectMetadata)
+      isDefined(objectMetadata) &&
+      isDefined(entityManager) &&
+      isDefined(internalContext)
    ) {
-      return handleDuplicateKeyError(error, objectMetadata);
+      return await handleDuplicateKeyError(
+        error,
+        objectMetadata,
+        internalContext,
+        entityManager,
+      );
    }

    if (error.message.includes('invalid input value for')) {
@@ -140,7 +140,7 @@ export class WorkspaceDeleteQueryBuilder<
        affected: result.affected,
      };
    } catch (error) {
-      throw computeTwentyORMException(error);
+      throw await computeTwentyORMException(error);
    }
  }

@@ -226,7 +226,12 @@ export class WorkspaceInsertQueryBuilder<
        this.internalContext,
      );

-      throw computeTwentyORMException(error, objectMetadata);
+      throw await computeTwentyORMException(
+        error,
+        objectMetadata,
+        this.connection.manager as WorkspaceEntityManager,
+        this.internalContext,
+      );
    }
  }

@@ -95,7 +95,7 @@ export class WorkspaceSelectQueryBuilder<
        identifiers: result.identifiers,
      };
    } catch (error) {
-      throw computeTwentyORMException(error);
+      throw await computeTwentyORMException(error);
    }
  }

@@ -121,29 +121,29 @@ export class WorkspaceSelectQueryBuilder<

      return formattedResult;
    } catch (error) {
-      throw computeTwentyORMException(error);
+      throw await computeTwentyORMException(error);
    }
  }

  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  override getRawOne<U = any>(): Promise<U | undefined> {
+  override async getRawOne<U = any>(): Promise<U | undefined> {
    try {
      this.validatePermissions();

      return super.getRawOne();
    } catch (error) {
-      throw computeTwentyORMException(error);
+      throw await computeTwentyORMException(error);
    }
  }

  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  override getRawMany<U = any>(): Promise<U[]> {
+  override async getRawMany<U = any>(): Promise<U[]> {
    try {
      this.validatePermissions();

      return super.getRawMany();
    } catch (error) {
-      throw computeTwentyORMException(error);
+      throw await computeTwentyORMException(error);
    }
  }

@@ -171,7 +171,7 @@ export class WorkspaceSelectQueryBuilder<

      return formattedResult;
    } catch (error) {
-      throw computeTwentyORMException(error);
+      throw await computeTwentyORMException(error);
    }
  }

@@ -197,17 +197,17 @@ export class WorkspaceSelectQueryBuilder<

      return formattedResult[0];
    } catch (error) {
-      throw computeTwentyORMException(error);
+      throw await computeTwentyORMException(error);
    }
  }

-  override getCount(): Promise<number> {
+  override async getCount(): Promise<number> {
    try {
      this.validatePermissions();

      return super.getCount();
    } catch (error) {
-      throw computeTwentyORMException(error);
+      throw await computeTwentyORMException(error);
    }
  }

@@ -240,7 +240,7 @@ export class WorkspaceSelectQueryBuilder<

      return [formattedResult, count];
    } catch (error) {
-      throw computeTwentyORMException(error);
+      throw await computeTwentyORMException(error);
    }
  }

@@ -140,7 +140,7 @@ export class WorkspaceSoftDeleteQueryBuilder<
        affected: after.affected,
      };
    } catch (error) {
-      throw computeTwentyORMException(error);
+      throw await computeTwentyORMException(error);
    }
  }

@@ -19,6 +19,7 @@ import { type AuthContext } from 'src/engine/core-modules/auth/types/auth-contex
 import { type QueryDeepPartialEntityWithNestedRelationFields } from 'src/engine/twenty-orm/entity-manager/types/query-deep-partial-entity-with-nested-relation-fields.type';
 import { type RelationConnectQueryConfig } from 'src/engine/twenty-orm/entity-manager/types/relation-connect-query-config.type';
 import { type RelationDisconnectQueryFieldsByEntityIndex } from 'src/engine/twenty-orm/entity-manager/types/relation-nested-query-fields-by-entity-index.type';
+import { type WorkspaceEntityManager } from 'src/engine/twenty-orm/entity-manager/workspace-entity-manager';
 import { computeTwentyORMException } from 'src/engine/twenty-orm/error-handling/compute-twenty-orm-exception';
 import {
  TwentyORMException,
@@ -223,7 +224,12 @@ export class WorkspaceUpdateQueryBuilder<
        this.internalContext,
      );

-      throw computeTwentyORMException(error, objectMetadata);
+      throw await computeTwentyORMException(
+        error,
+        objectMetadata,
+        this.connection.manager as WorkspaceEntityManager,
+        this.internalContext,
+      );
    }
  }

@@ -373,7 +379,12 @@ export class WorkspaceUpdateQueryBuilder<
        this.internalContext,
      );

-      throw computeTwentyORMException(error, objectMetadata);
+      throw await computeTwentyORMException(
+        error,
+        objectMetadata,
+        this.connection.manager as WorkspaceEntityManager,
+        this.internalContext,
+      );
    }
  }

@@ -1,15 +1,39 @@
+import { isDefined } from 'twenty-shared/utils';
+
 import { UserInputError } from 'src/engine/core-modules/graphql/utils/graphql-errors.util';
 import {
  type TwentyORMException,
  TwentyORMExceptionCode,
 } from 'src/engine/twenty-orm/exceptions/twenty-orm.exception';

+interface DuplicateKeyErrorWithMetadata extends TwentyORMException {
+  conflictingRecordId?: string;
+  conflictingObjectNameSingular?: string;
+}
+
 export const twentyORMGraphqlApiExceptionHandler = (
  error: TwentyORMException,
 ) => {
  switch (error.code) {
+    case TwentyORMExceptionCode.DUPLICATE_ENTRY_DETECTED: {
+      const duplicateKeyError: DuplicateKeyErrorWithMetadata = error;
+
+      const extensions: Record<string, unknown> = {
+        userFriendlyMessage: error.userFriendlyMessage,
+        ...(isDefined(duplicateKeyError.conflictingRecordId) &&
+        isDefined(duplicateKeyError.conflictingObjectNameSingular)
+          ? {
+              conflictingRecordId: duplicateKeyError.conflictingRecordId,
+              conflictingObjectNameSingular:
+                duplicateKeyError.conflictingObjectNameSingular,
+            }
+          : {}),
+      };
+
+      throw new UserInputError(error.message, extensions);
+    }
+
    case TwentyORMExceptionCode.INVALID_INPUT:
-    case TwentyORMExceptionCode.DUPLICATE_ENTRY_DETECTED:
    case TwentyORMExceptionCode.CONNECT_RECORD_NOT_FOUND:
    case TwentyORMExceptionCode.CONNECT_NOT_ALLOWED:
    case TwentyORMExceptionCode.CONNECT_UNIQUE_CONSTRAINT_ERROR: