Skip to main content

INVALID_CROSS_REFERENCE_KEY on a Salesforce deploy

Updated · By the Clientell AI team · How we write

Salesforce found an ID it could not resolve. In metadata deploys the usual cause is a custom app that points at profiles created in the same package, because the app saves first. Deploy the profiles first, or create the app by hand. In data loads, the user's profile cannot use that record type.

Error text (INVALID_CROSS_REFERENCE_KEY)

INVALID_CROSS_REFERENCE_KEY: invalid cross reference id

Message text as quoted in the sources below.

Validate the same package against the target first. The failed row names the component, even when the message does not name the ID.

What does INVALID_CROSS_REFERENCE_KEY mean?

Something in your deploy refers to a record by ID, and Salesforce cannot turn that reference into a real record. The message does not say which one.

Most missing-item errors say no X named Y found. This one names nothing, which is why it eats an afternoon.

What causes it?

  • A custom app that refers to profiles created in the same deploy. Salesforce saves the custom application before profiles. If the app has ProfileActionOverride entries for profiles that are new in this package, those profiles have no ID yet, the reference resolves to nothing, and the app fails (Gearset docs).
  • A record type the running user cannot use. The data variant reads Record Type ID value isn't valid for User. The profile of the user who loads the data does not have that record type enabled. The accepted answer on Stack Exchange is to give that profile the record type (Salesforce Stack Exchange).
  • A stale or wrong-org ID. Record IDs differ between orgs. If a flow, a data file or a custom setting carries a hard-coded sandbox ID, production cannot resolve it.

How do I fix it in Setup?

For the custom app case, which is the common metadata one:

  1. Open the failed row in Setup > Deployment Status > View Details and find the app named in the line.
  2. Create the profiles the app refers to in the target before you deploy the app. Or add the Profile type to the package, with those profiles selected, so they travel with the app.
  3. If it still fails, take the app out of this deploy, create it by hand in the target, and deploy everything else. Gearset lists both options.
  4. Validate again.

For the record type case:

  1. In the target, open Setup, Profiles, pick the profile of the user who runs the load, and open the object's record type settings.
  2. Enable the record type, or run the load as a user whose profile has it.

How do I fix it with the CLI?

Check the exact failing file first, because the error line gives the component:

sf project deploy start --source-dir force-app --dry-run --test-level NoTestRun -o target-org --json

Read details.componentFailures in the output, not only the top-level message.

How do I avoid it?

Deploy in order: profiles and permission sets before the apps that use them. Do not copy record IDs between orgs. Look them up by name in the target. The profiles vs permission sets guide explains why we keep access in permission sets, and the profile glossary entry defines the pieces. If your deploys keep hitting order problems, AI Salesforce deployments checks deploy order before a bundle ships.

Questions about INVALID_CROSS_REFERENCE_KEY

Why does the error not tell me which ID is wrong?

The message only says the reference could not be resolved. Use the component name on the failed row to find the file, then look for profile, record type or user references inside it.

Is invalid cross reference id the same as INVALID_CROSS_REFERENCE_KEY?

Yes. Deploys show the lower-case phrase. The API and data loads show the code, often with the record type ID.

Does it happen with connected apps?

Yes. A Stack Exchange question reports it when pushing a connected app with the CLI. Check which profiles or permission sets the app refers to.

Will a retry fix it?

Not by itself. The order of saves is what failed, so deploy the referenced items first.

Catch this before the deploy window

Clientell AI runs these checks on the bundle before the deploy, and asks before it changes anything in production. Platform deployments include a snapshot and rollback.

Book a call with an expertStart the 14-day trial, no cardSee AI Salesforce deployments

Sources: Gearset docs, invalid cross reference id on validation, Salesforce Stack Exchange, Invalid Cross Reference Key: Record Type ID value isn't valid for User, Salesforce Stack Exchange, pushing a Connected App results in invalid cross reference id.

All Salesforce deployment errors or paste your own error into the explainer