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.