Comment corriger INVALID_CROSS_REFERENCE_KEY dans les déploiements Salesforce

Un composant déployé fait référence à un autre enregistrement ou champ par un ID ou un nom d'API qui n'existe pas dans l'org cible.

Se produit lors de : la validation du déploiement des métadonnées et le DML à l'exécution sur des ID d'enregistrement

Ce que cela signifie

INVALID_CROSS_REFERENCE_KEY signifie que Salesforce a tenté de résoudre une référence à l'intérieur de vos métadonnées, un ID d'enregistrement, un nom d'API de champ, un page layout, une affectation de permission set, et n'a pas trouvé de correspondance dans l'org cible. La référence elle-même peut être parfaitement valide dans l'org d'origine ; le problème est que l'org qui reçoit le déploiement n'a pas encore de composant correspondant, ou n'en aura jamais.

Cela apparaît dans deux contextes distincts : au moment du déploiement, quand la Metadata API résout une référence de composant, et à l'exécution, quand Apex ou l'API transmet un ID d'enregistrement qui ne correspond à aucun enregistrement visible par l'utilisateur en cours dans cette org.

Diagnostic

Causes courantes

ID d'enregistrement codé en dur provenant d'une autre org

Un flow, un approval process ou une classe Apex stocke un ID d'enregistrement qui n'existe que dans la sandbox source, si bien que l'org cible n'a rien avec quoi le faire correspondre.

Dépendance déployée dans le mauvais ordre

Un champ, un record type ou un layout référencé par le composant en cours de déploiement n'a pas été inclus dans le même package ou n'est pas encore arrivé dans l'org cible.

Nom d'API obsolète ou renommé

Le composant a été renommé ou son nom d'API a changé dans une org, mais la référence qui pointe vers lui n'a jamais été mise à jour.

La solution

Remplacez les ID codés en dur par des lookups
Remplacez tout ID d'enregistrement codé en dur de 18 caractères par une requête SOQL, un Custom Metadata Type, ou un Custom Setting, afin que la référence se résolve par org.
```
Id defaultRecordTypeId = Schema.SObjectType.Case
    .getRecordTypeInfosByDeveloperName()
    .get('Support_Request')
    .getRecordTypeId();
```
Regroupez la chaîne de dépendances complète
Incluez chaque champ, record type et layout dont dépend le composant dans le même déploiement, et déployez dans l'ordre des dépendances.
Vérifiez que le nom d'API correspond exactement
Confirmez que le nom d'API du composant référencé dans l'org cible est identique, y compris le suffixe __c et le préfixe de l'objet.

En pratique

Comment Serpent évite cela

Serpent AI cartographie le graphe de dépendances complet avant qu'une tâche n'atteigne le déploiement, de sorte qu'une référence manquante ou renommée apparaisse comme un avertissement de scope plutôt que comme un déploiement en échec. Voir la bibliothèque des erreurs de déploiement Salesforce pour les erreurs associées.

Métadonnées et données dans un seul flux de déploiement dans Serpent

Prévention

Interdisez les ID d'enregistrement codés en dur en revue de code

Traitez tout ID littéral de 15 ou 18 caractères dans Apex, un Flow ou une formule comme un bloqueur de revue ; résolvez plutôt les références par nom d'API, ID externe, ou Custom Metadata Type.

Déployez dans un ordre de dépendances explicite, pas alphabétique ou par défaut

Définissez un ordre de déploiement explicite pour les métadonnées interdépendantes plutôt que de dépendre de l'ordre par défaut que votre outillage produit par hasard.

Recherchez toutes les références avant de renommer un nom d'API

Recherchez dans Apex, Flow, les formules et les layouts le nom d'API actuel d'un composant avant de le renommer, afin qu'aucune référence obsolète ne subsiste.

Erreurs associées

INVALID_ID_FIELDUn cas plus spécifique : l'ID correspond à un enregistrement réel, mais sur le mauvais objet.MALFORMED_IDUne erreur liée mais distincte : la valeur n'est pas du tout une chaîne d'ID valide, pas seulement une référence non résolue.MISSING_FIELDLa version spécifique aux list views et aux reports d'une référence que l'org cible ne trouve pas.MANAGER_NOT_DEFINEDLe cas de la hiérarchie des utilisateurs, où la référence qu'un approval process ne peut pas résoudre est un manager.

Questions fréquentes

INVALID_CROSS_REFERENCE_KEY, les réponses

INVALID_CROSS_REFERENCE_KEY signifie-t-il que j'ai perdu des données ?

Non. Cela signifie que le déploiement s'est arrêté avant de toucher l'org cible, car une référence à l'intérieur de vos métadonnées n'a pas pu y être résolue.

Les paramètres de partage peuvent-ils causer cette erreur même si l'enregistrement existe ?

Oui. Si l'utilisateur en cours ne peut pas voir un enregistrement en raison de sharing rules ou de org-wide defaults, Salesforce peut le traiter comme irrésolu, de la même manière qu'un enregistrement réellement manquant.

Cela se produit-il avec les champs standard, ou seulement personnalisés ?

Cela peut arriver avec les deux. Une référence à un champ ou un enregistrement standard que l'édition ou la configuration de l'org cible ne prend pas en charge se résout de la même manière qu'un composant personnalisé manquant.

Commencez gratuitement. Sans carte bancaire, sans installation, sans engagement.

Configuration en moins de 15 minutes. Aucune embauche DevOps nécessaire.

Commencer gratuitement Réserver une démo