Troubleshooting

Config Promotion surfaces its reasons inline — a blocked promotion, a failed record, an unresolved reference each shows why on the results or differential, not a silent failure. This page maps the common messages to their fixes.

Unresolved dependency (the rare exception)

Symptom: a record is reported as failed or skipped with an actionable message about a reference it couldn’t resolve in the target.

Why this is rare: normally you don’t manage dependencies at all — a promotion is self-contained. Pinion pulls every referenced record (and its owned children) into the bundle automatically, so the target ends up complete from a single promotion. You should almost never see an unresolved-dependency error.

When you do, it’s because the referenced record genuinely can’t travel in this promotion — for example a non-promotable target, or a record that can’t be auto-provisioned (such as a custom pricebook that has to be created by name). The engine surfaces this as an actionable per-record error rather than guessing.

Caught before you deploy. You don’t have to promote and then discover a gap. The workbench runs a pre-flight check and shows a missing-reference list before you apply — the specific references the selected records need that aren’t present (and can’t be auto-carried) in the target. Each entry names the exact record so you can act on it, rather than getting a generic “dependency error.” Resolve the list first, and the promotion goes through clean.

Fix:

  • Promote the referenced record first — map it in the Map & promote workbench and apply it, then re-run the original promotion.
  • Or use Deploy to Sandbox — pushing the whole catalog guarantees every referenced record is present, so there’s nothing left to resolve.

Unstamped records (can’t be promoted)

Symptom: a record you expect doesn’t appear, won’t map, or won’t promote — and other records are fine.

Why: a record with a blank SyncKey can’t be promoted (the SyncKey is the cross-org identity everything keys on). This usually means the record predates a feature, came from a source-deployed org, or was left over from an incomplete install.

Fix: run Backfill SyncKeys from the Maintenance card on the Deploy to Sandbox tab. It stamps every config record that’s missing a key and leaves keyed records untouched, so it’s safe to run anytime and re-running is a no-op. See Cross-org identity & install order.

Blocked promotion

Symptom: the preview or results show a blocked message and nothing is written.

Why: the guardrails on the receiving org refused the promotion. The common cases:

  • Writing into a production target from another production org — refused by design (a conservative default).
  • A sandbox that hasn’t been declared a sandbox, or an org whose role can’t be determined — the guardrail fails closed and blocks.
  • A cross-family promotion — the target only accepts promotions from orgs that share its promotion family (production and its refreshed sandboxes share a family automatically; two unrelated orgs don’t).

Fix: confirm you’re promoting in an allowed direction (typically production → sandbox, or within a family). Deploy to Sandbox only accepts sandbox targets. If two orgs should be the same family but aren’t, that’s an org-declaration task for your admin. The blocked message names the specific reason.

Connection or credential issues

Symptom: a promotion fails immediately with a connection error, or the target picker is empty.

Why and fix:

  • No targets listed — no connected target is registered yet, or you lack the Pinion Administrator permission set. Register a target, or check your permissions.
  • The callout fails — the target’s Named Credential is missing, misconfigured, or its authentication needs attention. The connection’s destination and auth live entirely in the Named Credential (a Salesforce platform feature); your admin configures it once per target. If a previously-working connection starts failing, the credential’s authentication may need to be re-established. Pinion surfaces the connection error inline rather than crashing.
  • HTTP 403 (Forbidden) from the target — the message reads like “Remote preview failed (HTTP 403): You do not have admin access to config promotion imports.” The connection works, but the user the Named Credential signs in as doesn’t hold Pinion Administrator in the target org. Assign that permission set to the promotion user in the target and retry. See Connecting orgs (Step 1).