← Documentation home

Troubleshooting & FAQ

• Sync appears stuck or partial
• Re-authorizing your Salesforce org
• The Salesforce login fails or shows an error
• Switching to a different Salesforce org
• Rate limits & API errors
• Why is a component or type missing?
• Removed & out-of-scope pages
• Permissions, scopes & data handling
• Live View: “You don’t have access to this data”
• FAQ

Sync appears stuck or partial

A sync that seems to sit at a partial percentage for a while is almost always normal progress on a large org, not a hang. MetaSync’s sync engine runs in short, scheduled cycles and spreads a big org’s work across several of them. This section explains the model so you can tell when to wait from when to worry.

The five-minute cycle model

MetaSync runs a scheduled trigger about every five minutes. Each run works through a queue of small work items — one for objects (chunked into batches so no single item is too large), one for Flows and validation rules, one for Apex, several for org-configuration types (security, integration, UI, layouts, custom settings), one each for Profiles, Permission Sets and Reports, then field-detail pages and the Data Dictionary / Coverage / Setup Audit Trail pages. A single cycle chains through as many queue items as fit its time budget, then stops and lets the next cycle pick up where it left off.

Note — Why a big org takes several cycles. Each cycle has a hard time budget (the scheduled function stops starting new items well before its limit so runs never overlap). On a large org there are more queue items than fit in one cycle, so the first full sync legitimately spans multiple five-minute cycles. The progress bar advances between cycles rather than continuously — this is expected. See How syncing works.

Incremental syncs are much faster

Only the first sync (or one right after you change the destination space or structure mode) is a full extract. After that, MetaSync runs incrementally: before each run it probes which types actually changed since the last successful sync and skips the rest, so most scheduled syncs finish in a cycle or two. See Scheduled Syncs.

How large or heavy items are split

• Objects are processed in batches of 75 — a 200-object org becomes three object items so extraction and publishing always fit the budget.
• Org-configuration metadata (the “misc” work) is split into five weight-balanced items — Security, Integration, UI, Layouts, and Custom Settings — so no single item tries to extract every config type at once.
• Heavy publish categories (for example Layouts) paginate across cycles, resuming from a saved cursor.
• Reports, Profiles, Permission Sets and field pages paginate by offset so a folder or a large list is spread over several cycles.

What “partial” status means

If the sync engine’s scheduled trigger is cut short while an item is mid-flight, that item is retried on the next cycle. An item is only abandoned after it has been cut short twice — the attempt counter is stamped before processing, so the third pickup sees attempts > 2 and skips it. (Two failed attempts, three pickups.) When that happens the run finishes and its Sync History entry is marked:

• success — Every queue item published. Nothing was skipped.
• partial — Some items published, but at least one heavy type was skipped after repeated trigger timeouts, or a component was lost to a transient read error. The status message names the skipped type(s), e.g. “Sync completed with 1 type(s) skipped — Skipped after repeated timeouts: layouts. Re-run to retry.” Everything else is up to date; just run another sync to pick up the skipped type.
• failed — Either every item was skipped, or the run hit a genuine error such as an expired Salesforce connection — including the degraded case below, where most types published but one failed to extract. See Re-authorizing your Salesforce org and Rate limits & API errors.

“One metadata type failed” (a degraded run)

This is different from a timeout skip. If a metadata type throws while extracting — a transient Salesforce error, a permissions change, a malformed component — MetaSync isolates the blast radius to that one type instead of letting an empty result be recorded as a complete extraction:

• Its pages and change snapshot keep the previous sync’s state — nothing is rewritten from the empty result.
• No removals are reported for it. This is the key protection: recording an empty list as complete would make the diff report every live component of that type as deleted — mass “Removed from Salesforce” banners, pruned index rows, and a flood of phantom high-risk entries in Change impact.
• Its incremental watermark is held, so the next run re-scans the window it missed rather than skipping past it.
• Sibling types in the same queue item publish normally — you don’t lose the whole run.

Note — How you’ll see it. The run is recorded with an error naming the type and cause (e.g. “miscIntegration: Extraction failed for: customLabels (…)”) rather than as a clean success — so a degraded run never masquerades as a good one. What to do: run another sync. A transient cause clears itself; a persistent one keeps naming the same type, which tells you where to look (usually a Salesforce permission on the integration user). See Sync History.

Note — A component the integration user can’t read is not a partial run. MetaSync separates a permanent read failure (an access error that will recur every run) from a transient one (retried first). A permanent one is disclosed on the type’s index — “N layouts not captured — no access”, naming each — and the run still completes normally, because otherwise an ungranted permission would hold every run at partial forever and force a full rewrite each time. If you want those components documented, grant the integration user read access (see Why is a component or type missing?) and re-sync. See “Not captured” on published pages.

When to wait vs when to worry

• Wait if the progress percent has moved within the last few minutes, or the status says work is queued for the next scheduled run — a large first sync simply needs more cycles.
• Wait if you see a “queued” message like “…publishing the next types in the next scheduled run (~5 min)”. The next cycle will continue automatically.
• Worry (act) if the status is failed or mentions the connection being expired or revoked — re-authorize the org (see Re-authorizing your Salesforce org).
• Worry (act) if the run is partial and names a skipped type you need — just run another sync; the incremental probe will re-attempt only what’s outstanding.

Note — Check Sync History for the real story. The Sync History view records each run’s status, duration, page create/update counts, per-type metadata counts, and any error message. It is the authoritative place to see whether a run succeeded, was partial, or failed — and exactly which type was skipped. See Sync History.

Re-authorizing your Salesforce org

How you repair a rejected connection depends on how it was made — the Connections tab offers the button that fits, so you don’t have to remember which you chose.

A sign-in connection holds a refresh token stored at connect time and exchanges it for a short-lived access token on each sync. If that refresh token is revoked or expires — someone removed the app’s authorization, the integration user was deactivated, the token was reset, or it simply aged out — MetaSync can’t authenticate and the sync stops until you re-authorize. Re-authorizing is a short flow: MetaSync reuses the app key and secret and the login URL already saved with the connection, so it asks for nothing but the Salesforce sign-in itself.

A Client Credentials Flow connection holds no token that can expire: it mints a fresh access token from the app’s key and secret on every run. What breaks it is a change in Salesforce — the secret rotated, the app replaced, the Client Credentials Flow unticked, or the Run As user deactivated. The repair is Update keys, a one-step dialog, and there is no sign-in involved.

How MetaSync detects a dead connection

When a sync fails to authenticate, MetaSync inspects the Salesforce error. Messages such as invalid_grant, expired access/refresh token, authentication failure, INVALID_SESSION_ID, invalid_client or inactive user are treated as an auth failure (not a transient glitch). The run is flagged accordingly so the UI can offer a one-click re-authorization rather than a generic error.

What you’ll see

• A warning banner titled “Salesforce connection needs re-authorization” appears across the app: “The stored Salesforce connection was rejected (expired or revoked token), so syncs will keep failing until it is reconnected.”
• On a sign-in connection: a Re-authorize Salesforce button on the banner. Under Connections, the header carries a Re-authorize button and the org’s Status column reads Needs re-authorization, with a Re-authorize button on the row itself. All of them open the same two-step flow.
• On a Client Credentials Flow connection: the banner offers Update app keys instead, the Status column reads Check app keys, and the header and row buttons read Update keys. All of them open the one-step dialog below.
• The related Sync History / progress message reads: “Salesforce connection expired or was revoked — reconnect it under Connections.”

Steps to re-authorize (sign-in connections)

1. Open the MetaSync admin page (as a Confluence admin, or as a user holding the App admin role — see Permissions, scopes & data handling).
2. Click Re-authorize Salesforce on the banner, or go to Connections and use Re-authorize in the header or on the org’s row.
3. Step 1 of 2 summarises the connection MetaSync is about to re-authorize: its display name, org type, login host and a masked hint of the saved app key. Check it names the org you mean, then click Continue to Salesforce login.
4. Step 2 of 2 — click Open Salesforce login and sign in as the integration user in the new tab, exactly as during Onboarding: from install to first sync. If Salesforce auto-signs you in as someone else from an existing browser session, choose Use a Different Account first: the refresh token belongs to whoever authorizes.
5. Once authorized, run a sync (or wait for the next scheduled one). The incremental probe means only what changed since the last success is re-published.

Tip — Nothing is re-asked. Re-authorizing uses the app keys already saved with the connection — the ones you entered when you first connected, together with its login URL — so there are no credential fields to fill in and no chance of a typo. There is no destination step either: your space, home page title, page structure, managed-package choice, metadata scope and schedules are not part of this flow and are not written by it. The step-1 summary says the same thing on screen. See Connected Salesforce Org.

Note — If the app keys themselves changed. If the app’s secret was reset in Salesforce, or the External Client App itself was replaced, the saved keys can’t work and the re-authorization fails at Salesforce with invalid_client. Use the Connect a different org or enter new keys instead link on step 1: it switches to the full three-step flow, where the current keys can be pasted in. See The Salesforce login fails or shows an error.

Steps to update the keys (Client Credentials Flow connections)

1. Open the MetaSync admin page (as a Confluence admin, or as a user holding the App admin role — see Permissions, scopes & data handling).
2. Click Update app keys on the banner, or go to Connections and use Update keys in the header or on the org’s row.
3. The dialog is a single step, titled Update app keys and naming the connected org. Paste the current app key and secret from the External Client App (Settings → OAuth Settings); the My Domain login URL is shown read-only from the saved connection, so there is nothing else to fill in.
4. Click Test and save. MetaSync exchanges the pair for a token and saves it only once Salesforce accepts, so a mistyped secret can’t replace a working one. If Salesforce refuses, the message tells you which half of the setup to check — see The Salesforce login fails or shows an error.
5. Run a sync (or wait for the next scheduled one). The incremental probe means only what changed since the last success is re-published.

Tip — Updating the keys touches nothing else. This dialog writes the app key and secret and nothing more: your Confluence space, home page title, page structure, managed-package choice, metadata scope and schedules are not part of it. It also stays on the same org — the login URL comes from the saved connection and is not editable here. To point MetaSync at a different org, use Switch org; see Switching to a different Salesforce org.

Note — If re-authorization keeps failing. A repeated failure usually points back to Salesforce. On a sign-in connection: confirm the External Client App (or Connected App) still exists and is authorized, the integration user is active, and the OAuth policy permits refresh tokens. On a Client Credentials Flow connection: confirm Enable Client Credentials Flow is still ticked on the app and that Policies → Client Credentials Flow → Run As names an active user. MetaSync only ever requests the api scope (plus refresh_token where a person signs in); what the connection can read is governed by that user’s Salesforce permissions.

Note — Changing orgs is a separate action. Both repairs above target the org already connected. To document a different org, use Switch org on the Connections tab instead — it asks for the new org’s connection method, keys and destination. See Switching to a different Salesforce org.

The Salesforce login fails or shows an error

Client Credentials Flow connecting is a two-party exchange: MetaSync posts the app’s key and secret to your My Domain URL and Salesforce answers with a token or a refusal, shown as a red banner on step 3. There is no browser tab and no callback, so only the first two entries below can apply.

Web Server Flow is a three-party handshake: MetaSync builds the login link, Salesforce shows its login page and sends you back to MetaSync’s Callback URL, and MetaSync exchanges the code it receives for a refresh token. Any party can refuse. Salesforce shows some refusals on its own page in the tab that opened (the code is in the address bar, as error=redirect_uri_mismatch and the like) and hands others back to MetaSync, which shows them as a red banner in the connect modal; if nothing comes back at all, MetaSync stops waiting after a few minutes and says so. Find the code or message you saw below.

Error codes and messages

• Client Credentials Flow: “Salesforce rejected the Consumer Key or Secret, or the Client Credentials Flow is not enabled on the app.” — Salesforce answered invalid_client, which covers both halves of that sentence. Re-copy the key and secret from the app’s Settings → OAuth Settings → Consumer Key and Secret — a leading or trailing space is enough to break it — and check you are pointing at the org that owns the app, since a sandbox’s key does not work against production. Then confirm Enable Client Credentials Flow is ticked on that app’s OAuth settings: without it Salesforce refuses the exchange no matter how correct the pair is. For an app created minutes ago, allow Salesforce a little time to activate it.
• Client Credentials Flow: “The app’s Client Credentials Flow has no Run As user, or that user cannot log in.” — Salesforce answered invalid_grant: the key and secret are right, but there is no user for the token to act as. Open the app’s Policies → Client Credentials Flow and set Run As to the integration user, then try Test and connect again. If it is already set, check that user is active, is not frozen or locked out, and holds the permission set from The integration user. The Permitted Users policy is not the cause — it does not apply to the Run As user.
• Client Credentials Flow: “login.salesforce.com and test.salesforce.com are not accepted for this flow” — MetaSync refuses those two hosts on step 1, before contacting Salesforce, because the Client Credentials Flow token request has to go to the org’s own domain. Paste the org’s My Domain URL from Setup → My Domain — https://<name>.my.salesforce.com — or switch the connection method to Web Server Flow, which accepts all three org types.
• redirect_uri_mismatch — Salesforce found the app from the Consumer Key, but MetaSync’s Callback URL is not on that app’s callback list. Open the External Client App (or Connected App) whose Consumer Key you pasted — an org often holds several similarly named ones — and confirm the URL shown in step 1 of the connect dialog is there character for character, then Save. External Client App callback URLs are edited in Setup only. A callback saved moments ago can take a few minutes to be honoured, so wait briefly and click Open Salesforce login again.
• invalid_client_id / client identifier invalid — The Consumer Key matched no app in the org you were sent to. Re-copy it from the app’s Settings → OAuth Settings → Consumer Key and Secret (a leading or trailing space is enough to break it), check you are logging into the org that owns the app — a sandbox’s key does not work against production — and, for an app created minutes ago, allow Salesforce a little time to activate it.
• OAUTH_APP_ACCESS_DENIED / user hasn’t approved this consumer — The app’s Permitted Users policy is Admin approved users are pre-authorized, and the user you signed in as is not on the list. On the app’s Policies, assign the integration user’s profile or permission set to the app, then sign in again as that user. Keep this policy — it is the one The integration user recommends; the fix is the assignment, not switching to self-authorisation.
• Please use your My Domain URL / the login page refuses the org — The org’s My Domain policy blocks the shared login.salesforce.com page (Setup → My Domain → Policies → Prevent login from https://login.salesforce.com). Go back to step 1 of the connect dialog, set Org type to My Domain URL, and paste the org’s own login URL — https://<name>.my.salesforce.com for production or Developer Edition, https://<name>--<sandbox>.sandbox.my.salesforce.com for a sandbox. Only Salesforce login hosts are accepted there; a Lightning or Experience Cloud address pasted by mistake is refused with a hint under the field. MetaSync stores the URL with the connection and reuses it when you Re-authorize, so you set it once.
• Token exchange failed / invalid_grant — Salesforce sent you back, but the one-time code it issued was refused when MetaSync exchanged it. Two causes cover nearly every case: the code expired because the Salesforce tab sat open for a while before you signed in — codes live for minutes, so start again from Open Salesforce login and complete the sign-in promptly; or the Salesforce tab was reopened or reloaded from history, which breaks the PKCE proof MetaSync attached to that particular attempt — again, start again from the modal rather than reusing the old tab.
• Authorization failed: session expired — The Salesforce tab called back with a login attempt MetaSync has no record of — it was completed already, or it aged out while the tab sat open. The Salesforce page says the same thing. Close that tab, click Back in the dialog, then Continue to Salesforce login and use the fresh Open Salesforce login.
• Authorization timed out — MetaSync waited for Salesforce to call back and nothing arrived within a few minutes — usually because the Salesforce tab was closed before sign-in finished, or the error happened on the Salesforce page (see above) and the callback never fired. Click Back, then Continue to Salesforce login to start a fresh attempt.
• Destination not set — The org connected but the Confluence space could not be saved. Not a login problem: see the note in Onboarding: from install to first sync and set the space under Connections → Edit destination.
• The connection succeeded, then the first scheduled sync failed to authenticate — On a sign-in connection this means the stored refresh token was already spent when MetaSync came to use it. Two causes cover it. Something else is refreshing with the same token: another client — a script, a CI job, a data-loader profile, a second tool authorised as the same user on the same app — refreshed first, and Salesforce accepts a given refresh token only once when rotation is on, so MetaSync’s copy is dead. Give MetaSync an External Client App of its own, authorised by an integration user nothing else uses. Two refreshes raced: two MetaSync jobs asked for a token in the same moment and one used the token the other had just replaced. Re-authorize under Connections and it settles, because a single access token then serves both for up to 90 minutes. Rotation itself is not a cause — MetaSync stores each rotated token as Salesforce issues it and re-reads the newest stored one before every refresh. A Client Credentials Flow connection cannot hit this at all: it holds no refresh token.

Check the app you pasted the callback into

1. In Salesforce Setup, open External Client App Manager (and App Manager for legacy Connected Apps) and list every app whose name resembles the one you created — a trial app, a colleague’s copy and a packaged app can all sit side by side.
2. Open the one whose Consumer Key begins with the same characters as the key you pasted into MetaSync. That is the only app whose settings matter for this connection.
3. On its OAuth settings, confirm the Callback URL shown in step 1 of the connect dialog (next to its Copy button) is present exactly, and that PKCE is on — the full checklist is in Onboarding: from install to first sync.
4. If the Consumer Secret was reset since you copied it, copy the current one and start the connection again from step 1.

Note — Still stuck?. Walk the connection through once more with Onboarding: from install to first sync beside you — nearly every failed connect is one missing setting on the Salesforce app. A connection that worked and then stopped is a different problem: see Re-authorizing your Salesforce org.

Switching to a different Salesforce org

MetaSync documents one Salesforce org per Confluence site, so there is no “add a second org” — and, deliberately, no Disconnect or Delete-connection button either. Replacing the connected org has its own action: Switch org, on the Connections tab. It runs the full three-step connect dialog under the title Switch the connected org, with a warning that finishing it replaces the connection: the moment the new org accepts, its credentials overwrite the stored connection in place. It is a separate action from the repair buttons — Re-authorize and Update keys — which always target the org already connected (Re-authorizing your Salesforce org). This section walks through exactly how to switch, and what to expect afterwards.

Note — Why there is no Disconnect button. Because MetaSync is single-org, a connection is never deleted on its own — it is only ever replaced (by switching to another org) or purged entirely (by uninstalling the app, which removes all stored credentials and data — see Permissions, scopes & data handling). A standalone “disconnected” state would only stop scheduled syncs while leaving credentials behind, so the app doesn’t offer one. If you just want syncing to stop, remove the schedule instead — see Scheduled Syncs.

Before you switch

• Have OAuth app credentials for the new org ready — the Consumer Key and Consumer Secret of an External Client App (or Connected App) in that org, set up for the connection method you want, exactly as in Onboarding: from install to first sync. On the sign-in method the Callback URL that app needs is the same one your current app uses; step 1 of the dialog shows it with a Copy button, so you can create the new org’s app from there. On Client Credentials Flow there is no callback — have the new org’s My Domain URL and its Run As user ready instead.
• Decide where the new org’s documentation should live. Strongly consider a different Confluence space (or at least a different parent page and home-page title) than the old org used — see the warning below about title collisions.
• If your metadata scope uses “selected objects”, note the list down: it names objects from the old org, and those API names may not exist in the new one. Review the scope after switching — see Metadata Types & scope.

Switching step by step

1. Open the MetaSync admin page (as a Confluence admin, or as a user holding the App admin role) and go to Connections.
2. Choose Switch org in the header. The dialog opens on Switch the connected org, with a warning banner that completing it replaces the current connection.
3. Step 1 of 3 — Salesforce app. Pick the Connection method for the new org first — it can differ from the one the old org used. On Client Credentials Flow, paste the new org’s My Domain login URL, Consumer Key, Consumer Secret and a display name. On Web Server Flow, the Callback URL sits at the top with a Copy button (the new org’s OAuth app needs it on its callback list), then pick the org type — Production / Developer (login.salesforce.com), Sandbox (test.salesforce.com), or My Domain URL if the new org blocks the shared login page (paste its https://<name>.my.salesforce.com address) — and enter the key, secret and display name. Click Next: Confluence destination.
4. Step 2 of 3 — Confluence destination. The fields arrive prefilled from the current connection — the space, home page title, page structure and managed-package choice the old org publishes with. Change them here if the new org should publish somewhere else (read the warning below first); leave them as they are to publish into the same place. Next: Connect.
5. Step 3 of 3 — connect. On Client Credentials Flow, click Test and connect and check the org name and Run As user it reports back are the new org’s. On Web Server Flow, click Open Salesforce login and make sure you sign into the new org — if Salesforce auto-signs you into the old org from an existing browser session, choose Use a Different Account (or log out of Salesforce first). Sign in as that org’s integration user.
6. The moment the connection completes, the new org’s credentials replace the old ones — the old connection is gone and every future sync (manual or scheduled) reads the new org, publishing to the destination you confirmed in step 2.
7. Run a sync (or wait for the next scheduled one) and review your metadata scope if you had selected specific objects.

What to expect after the switch

• The first sync is a full sync — MetaSync’s change tracking is stored per org, so there is no incremental watermark for the new org — the first run extracts and publishes everything in scope, and on a large org spans several five-minute cycles, just like onboarding. See Sync appears stuck or partial. Incremental syncs resume from the second run.
• The old org’s pages are not deleted — MetaSync never deletes Confluence pages — that holds here too. Every page published from the old org stays in its space. If you no longer want them, archive or delete them yourself in Confluence, or leave them as a historical record. See Removed & out-of-scope pages.
• Site-wide views show old-org data until the new org syncs — The Data Dictionary, Coverage, Setup Audit Trail, dependency graph and governance reports are stored per Confluence site (not per org), so they keep showing the old org’s results until the new org’s first sync or report run overwrites them. Sync History keeps its existing entries, so runs from both orgs will appear in the same list.
• Your configuration carries over — The metadata scope and type toggles, schedules and notification settings all carry over untouched, and the destination is whatever you confirmed on step 2 — prefilled from the old org unless you changed it. That’s convenient, but it’s also why step 2 is worth reading rather than clicking through: those settings were chosen for the old org.

Warning — Syncing the new org into the old org’s space overwrites colliding pages. MetaSync updates pages by title within the destination space. If the new org publishes into the same space as the old one, any page whose title matches — the home page, category indexes like Objects or Flows, and any component with the same name (think Account, Contact, standard objects generally) — is rewritten with the new org’s content, while pages unique to the old org are simply left behind, stale and unlabeled. The two orgs’ documentation will silently interleave. Because step 2 arrives prefilled with the old org’s destination, publishing into the same space is what happens if you click straight past it. To keep a clean history, change step 2 to a different space (or at least a different parent page and home-page title), or archive the old pages first.

Starting completely clean instead

If you want to erase every trace of the old connection rather than overwrite it — credentials, tokens, sync snapshots, history, configuration and caches — uninstall MetaSync from Manage apps and reinstall it. A preUninstall routine purges all stored installation data from Forge storage before the app is removed, after which a fresh install starts with an empty slate and the normal Onboarding: from install to first sync flow. As always, uninstalling does not delete the Confluence pages that were published — remove those yourself if you want them gone. See Permissions, scopes & data handling.

Note — Related. Re-authorizing the same org after an expired or revoked token is covered in Re-authorizing your Salesforce org. The Connections tab itself — the connection table, the connect dialog’s three steps and the Edit destination modal — is documented in Connected Salesforce Org.

Rate limits & API errors

MetaSync reads a lot of metadata, so it is deliberately conservative about how hard it calls the Salesforce APIs. It batches requests, caps concurrency, and retries transient failures — so most rate-limit blips recover on their own without you doing anything.

How 429 / rate limits are handled

• Token refresh (HTTP 429) — If exchanging the refresh token is rate-limited, MetaSync waits 20 seconds and retries the exchange once. If it still fails, the run stops and reports the error (a genuine 429 on the same Connected App won’t clear by switching endpoints).
• Metadata reads — Component metadata is read in batches of up to 10, in concurrency-capped parallel waves (at most 5 batches at once) to stay under Salesforce’s concurrent-request throttle. Each batch retries up to 2 times with a short escalating backoff (500 ms × attempt); a batch that still fails returns empty rather than sinking the whole extraction.
• Bulk queries — Heavy per-component queries (for example validation rules) are issued in bounded batches instead of all at once, specifically to avoid tripping HTTP 429.
• Access-token reuse — A valid Salesforce access token is cached and reused across queue items (with a safety margin before expiry) so MetaSync doesn’t hammer the OAuth token endpoint on every item — the token endpoint is itself rate-limited.

Note — Salesforce API consumption. A full first sync of a large org makes many read calls and will use a noticeable slice of that day’s API quota; incremental syncs afterward are far lighter because unchanged types are skipped. If your org is close to its daily API limit, prefer a less frequent schedule and a narrower scope — see Why is a component or type missing? and Scheduled Syncs.

What surfaces on failure

• A single batch or type that fails after its retries is logged and skipped; the run continues and finishes as partial if other work published (see Sync appears stuck or partial).
• A rate-limit or transient failure that halts authentication is reported on the run with its error message; re-running usually succeeds once the limit window clears.
• The full status, duration and error message for every run live in Sync History — check there first to see whether a failure was a rate limit, an auth problem (Re-authorizing your Salesforce org), or something else.

Why is a component or type missing?

If a component, or a whole metadata type, isn’t showing up in your documentation space, work down this checklist — the cause is almost always one of these, in roughly this order of likelihood.

• 1. The type’s toggle is off — In the metadata scope/type selection, that type may be switched off. If a type is deselected, MetaSync doesn’t extract or publish it. Turn it on and re-sync. See Metadata Types & scope.
• 2. The object isn’t in scope — For object-scoped items (fields, record types, page layouts, validation rules on a specific object), the object itself must be selected. If you chose “selected objects” rather than “all objects”, anything on an unselected object is skipped. See Metadata Types & scope.
• 3. It’s from a managed package — By default MetaSync excludes managed-package (namespaced) components — exactly five types are filtered on namespace: permission sets, permission-set groups, muting permission sets, Lightning Web Component bundles and Aura component bundles. Enable the include-managed-package option if you need them. See Managed packages & standard vs custom.
• 4. You’re not an admin (whole app is gated) — If you can’t see the admin controls at all, that’s expected. There are four tiers: Confluence admins can do everything; a granted user holding the App admin role can do everything except manage who has access; a granted viewer sees a reduced set of tabs with configuration actions disabled; anyone else sees a notice that the app is managed by admins — and can still read the published pages. If you need to configure the connection, ask an admin for the App admin role. See Permissions, scopes & data handling.
• 5. The type isn’t supported — MetaSync documents a large but finite set of metadata types. If a type isn’t in the reference index, it isn’t synced yet. Browse the supported types at the metadata reference.
• 6. Extraction returned empty — A type’s extraction can come back empty because the org genuinely has none of it — or because that type failed to extract. In the failure case MetaSync demotes the type: its pages keep the previous sync’s content, no removals are reported for it, and the run is recorded with an error naming it rather than as a success. Check Sync History for the per-type counts and the error, and see the degraded-run section in Sync appears stuck or partial.
• 7. It’s there, just truncated — On very large components, long lists (related objects, “Referenced by”, etc.) are capped with a note showing how many of the total were rendered — so an item may be present but below the cap. See Truncation & display limits.
• 8. The page says “Not captured” — The component is documented, but that particular attribute is one MetaSync doesn’t read from Salesforce. It does not mean your org has none of it — check the value in Setup. See “Not captured” on published pages for the full list of which fields these are and where to look instead.

Note — Still missing after all that?. Confirm a sync has actually run since you added the component or changed scope, and that it finished (not partial with that type skipped). A fresh Sync now after adjusting scope is the quickest way to force a re-check. If the page EXISTS but is missing a detail you expect — and the component itself has not changed in Salesforce — Sync now will not fix it: an incremental run only re-publishes components that changed, so an unchanged component keeps its older page. That is what Full resync is for. See Sync appears stuck or partial and Overview dashboard.

Removed & out-of-scope pages

MetaSync keeps your documentation honest when the underlying org changes — but it does so by labeling pages, never by deleting them. Two distinct situations are handled with two distinct banners.

Note — A page never gets a removal banner just because a sync failed. Removal detection only runs for a metadata type whose complete list was extracted this run. If a type fails to extract, it is demoted and no removals are reported for it — so a transient Salesforce error can’t banner every component of that type as deleted. See the degraded-run section in Sync appears stuck or partial.

A component was removed from Salesforce

When a sync’s change-detection notices that a component MetaSync previously documented is no longer in the org, it prepends a warning banner to that component’s existing page. The banner reads: **“Removed from Salesforce — this component was no longer found in the org when MetaSync synced on . The page is kept for history and will not be updated further."** The page stays in place (useful as a historical record) and the banner is idempotent, so re-syncs won't stack duplicates.

A page fell out of your sync scope

If you turn a metadata type off (or narrow object scope), the component may still exist in Salesforce — MetaSync just no longer documents it. The “Housekeeping — pages no longer in scope” tool (under the metadata scope settings) finds those now-unmaintained pages and lets you label them. It prepends a softer info note: **“Removed from sync scope — this metadata type was excluded from MetaSync’s sync selection on , so this page is no longer updated. The component may still exist in Salesforce."**

A leftover or duplicate page of a type you still sync

The same tool also finds pages of a still-enabled type published under a title that no longer matches any current component — the residue of a rename or a page-title change. They’re listed under the category Leftover / duplicate (detected for Profiles and Permission Sets), alongside a short list of recognised placeholder titles that never correspond to a real component, listed as Stale page. They get the same reversible info note as a de-scoped page (the note’s wording is shared, so it refers to the sync selection even on a leftover page) — the point is that a page you’d otherwise never notice stops looking like current documentation. See Metadata Types & scope for how detection works.

1. Open the metadata scope settings and find Housekeeping — pages no longer in scope.
2. Choose Find pages no longer in scope to scan. Candidates are listed with a category lozenge and nothing is pre-selected.
3. Tick the pages you want flagged and choose Label N pages as no longer updated. MetaSync prepends the info note to each — it does not delete them.

Warning — MetaSync never deletes Confluence pages. By design, MetaSync only ever creates, updates, or annotates pages — including the removed-from-Salesforce and out-of-scope banners above. It never deletes a Confluence page. If you want a labeled page gone, delete it yourself in Confluence. (This is also true on uninstall — see Permissions, scopes & data handling.)

Note — Note the two banners are different. “Removed from Salesforce” (warning) = the component is gone from the org. “Removed from sync scope” (info) = you de-selected the type, or the page is a leftover/duplicate; the component may still exist. Team-annotation content on either page is preserved as always — see Managed regions & team annotations.

Permissions, scopes & data handling

MetaSync is a Forge app: it runs on Atlassian’s infrastructure, and everything it can do is declared up front in its manifest and reviewed by Atlassian. This section lays out exactly which permissions it holds, who can use it, and where your data goes.

Every Forge scope MetaSync requests

All ten scopes declared in manifest.yml, and why each is needed. A test fails if this table and the manifest disagree.

Who can use the admin page

Only Confluence administrators can operate MetaSync. Every sensitive resolver checks the caller’s group memberships (via read:user:confluence + read:group:confluence) and allows the call only if they belong to an admin group. The check fails closed — any error or missing membership is treated as “not an admin”. Someone who is neither an admin nor granted access sees a notice headed “MetaSync is managed by Confluence admins” — but the documentation pages MetaSync publishes are still available in the Confluence space like any other page.

Granting access and roles to non-admins

An admin can allow-list named users or groups under Connections → Additional access, giving each granted user one of two roles. A Viewer sees only Overview, Change impact, Governance, Sync history and Documentation; Metadata types, Schedules and Connections are hidden, and within the visible pages the configuration actions (build a governance snapshot or ZIP, build an access snapshot, mark a change reviewed, connect an org) render disabled with an explanation instead of failing on click. Granted groups are always viewers.

An App admin gets the full dashboard and can do everything a Confluence admin can do inside MetaSync — connect or replace the Salesforce org, edit the destination, set the metadata scope, manage schedules, run and cancel syncs, change notification settings and build every report. This is the role to use when the Confluence admin doesn’t administer Salesforce and needs someone else to create the External Client App and complete the OAuth connection.

Note — The UI is a convenience, not the control. Hiding and disabling controls only prevents dead ends. The gated resolvers reject an under-privileged caller server-side regardless of what the UI shows. The grant list and the role assignments can only be read or edited by a real Confluence admin — an App admin can never change who has access, including their own role, so the role cannot be used to escalate or to lock admins out.

Warning — Additional access ≠ access to the published pages. Additional access governs the MetaSync app only. It has no bearing on the documentation pages MetaSync publishes into Confluence: those are ordinary Confluence pages, governed entirely by space permissions. Granting someone access here does not give them the pages, and leaving someone off the list does not hide the pages from them — someone with no MetaSync access at all can still read every published page if they can see the space. To restrict the documentation, restrict the destination space in Confluence.

Note — “Restricted to Confluence admins” after an update. The admin gate uses scopes (read:user:confluence, read:group:confluence) that may have been added in an update. If an admin suddenly can’t access MetaSync, the app’s updated permissions likely need approval: go to Manage apps → MetaSync and approve the requested access.

Where your data goes

The data path is deliberately short and one-directional: Salesforce → MetaSync (Forge) → Confluence pages. MetaSync reads metadata from Salesforce, transforms it inside the Forge runtime, and writes pages into your Confluence space. It reads your org’s configuration, not your business records, and it is read-only in behaviour: the app issues no create, update, deploy or delete call against Salesforce, ever. Be precise about what carries that guarantee, though — the api OAuth token itself is not write-blocked, because Salesforce offers no read-only or metadata-only scope. What MetaSync does with the token is one-way by construction; what the token could do is bounded by the integration user’s permissions. See Why the integration user cannot read records.

Note — Outbound network destinations. MetaSync’s manifest permits outbound calls to Salesforce OAuth/API endpoints (login.salesforce.com, test.salesforce.com, *.my.salesforce.com, *.salesforce.com) plus the Confluence Cloud API it runs on. The only other destinations are the optional notification webhooks you configure yourself: Slack (hooks.slack.com) and Microsoft Teams via Power Automate (*.logic.azure.com, *.powerplatform.com). These are opt-in and off by default — no request is ever made unless you paste a webhook URL under Connections → Notifications. Even then the body is a status-only line (org name, sync status, truncated error, run id, page counts, per-type counts, duration) and never any Salesforce record content.

Where credentials and tokens live

What MetaSync holds depends on how the org was connected, and both possibilities live in the same place. A sign-in connection stores a Salesforce refresh token, used only to obtain short-lived access tokens at sync time; when Salesforce rotates that token on a refresh, MetaSync stores the replacement and re-reads the newest stored one before the next refresh. A Client Credentials Flow connection stores the app key and secret instead and exchanges those for an access token directly — there is no refresh token in it at all. Either credential, along with the connection details, is held in Forge’s app storage, keyed per installation. Access tokens are cached briefly (with a safety margin before expiry) to avoid over-calling the OAuth endpoint. Nothing is stored outside Forge, and credentials are never written into Confluence pages.

What happens on uninstall

MetaSync registers a Forge preUninstall handler that runs before the app is removed. It calls a routine that purges all installation data — Salesforce credentials and tokens, snapshots, sync history, configuration and caches — from Forge storage, so nothing is left orphaned. This is what backs the deletion-on-uninstall guarantee. As everywhere else, uninstalling does not delete any Confluence pages you’ve published; if you want the documentation gone, remove those pages yourself. See Removed & out-of-scope pages.

Live View: “You don’t have access to this data”

A viewer opens Live View and sees an informational panel headed “You don’t have access to this data” with a Retry button, instead of the tables and diagrams. This is a permission outcome, not a fault — nothing is broken and no sync is needed.

Why it happens

• The viewer can’t see the space. Live View’s data calls are checked as the viewing user against the Confluence page/space the macro sits on. If they can’t open that space in Confluence, they can’t read the data through the macro either. Fix it in Confluence’s space permissions — MetaSync deliberately has no override.
• The viewer declined or dismissed the one-time “Allow access” prompt. Because the check runs as the user, Atlassian asks each person for consent the first time they open Live View. Declining it means MetaSync can’t confirm what they may see, so it fails closed.
• The macro is embedded outside your documentation space. The page check is only trusted on the space MetaSync publishes into. Anywhere else, the viewer must be a Confluence admin or be on the Additional access list.

Note — If they declined the “Allow access” prompt. Ask them to reload the page and accept the prompt when it reappears, then click Retry in the panel. If it doesn’t reappear, opening the page in a new browser tab (or a fresh session) will re-ask. Accepting grants MetaSync nothing beyond the ability to check that viewer’s Confluence access — it never grants access to Salesforce, and Live View still shows only what your last sync documented.

Warning — One panel, not five errors. The denial is rendered once for the whole macro, so clicking between the five tabs won’t stack up repeated messages. Genuine failures (a storage read that broke) still show as a red Error: … on the affected tab — if you see that instead, it isn’t a permission problem.

Related: Live View overview · Permissions, scopes & data handling · Additional access.

FAQ

• Does MetaSync modify my Salesforce org? — No. MetaSync never writes, updates or deletes anything in Salesforce — its only writes are to Confluence pages. That is a property of the app’s behaviour rather than of the OAuth token: the api scope is not write-blocked, because Salesforce offers no read-only scope. The guarantee is that no write path exists in the app, and the bound on what the token could otherwise reach is the integration user’s permission set. See Permissions, scopes & data handling and Why the integration user cannot read records.
• Can I edit the generated pages? — Yes, safely — as long as you keep your notes in the right place. MetaSync only rewrites its own managed region on each sync; your Team Notes section and the Team annotations table below it are preserved. And if MetaSync can’t read a page’s current content, it skips the update and retries next sync rather than overwriting what it couldn’t see. Edits made to the auto-generated content itself are overwritten on the next sync. See Managed regions & team annotations.
• A page says “Not captured” — is that a bug? — No. It means MetaSync does not collect that particular detail from Salesforce — it is not a claim that your org has none of it. It replaces the old 0 / — / None, which read as measured facts on compliance pages. “Not captured” on published pages lists every field this applies to and where to check the real value in Setup.
• How fresh is the documentation? — As fresh as your last completed sync. Syncs run at the cadence you schedule — hourly, daily or weekly, see Scheduled Syncs; the engine’s five-minute cycle only governs how a running sync progresses, not how often one starts. So on a daily schedule the documentation can be up to a day behind the org, by design. Each page shows its last-synced date, and Sync History shows when each run happened.
• Can I sync more than one Salesforce org? — MetaSync documents one Salesforce org per Confluence site — the admin UI is single-org. To document a different org, replace the connection with Switch org on the Connections tab; the full walkthrough (including what happens to the old org’s pages) is in Switching to a different Salesforce org.
• How do I disconnect or remove the connected org? — There is intentionally no Disconnect / Delete-connection button. The connection is either replaced — use Switch org on the Connections tab and log into a different org, see Switching to a different Salesforce org — or purged entirely by uninstalling the app, which deletes all stored credentials and data. To merely stop syncing, remove the schedule instead (Scheduled Syncs).
• What happens to my pages if I change the destination space or structure mode? — Changing the destination space (or switching page-structure mode) forces the next sync to be a full sync, so the new space/layout gets the complete page tree rather than just incremental changes. Pages already published in the old space are left in place (MetaSync never deletes them). See Reading your documentation space and Removed & out-of-scope pages.
• How do I reduce what gets synced? — Narrow the metadata scope: turn off types you don’t need, choose “selected objects” instead of all objects, and leave managed-package components excluded. A smaller scope means faster syncs and lower Salesforce API usage. See Metadata Types & scope and Managed packages & standard vs custom.
• What’s the difference between the Excel and CSV exports? — CSV is a single flat table, ideal for quick filtering or importing elsewhere. Excel (XLSX) is a multi-sheet workbook with formatting and notes — better for handing an access review or governance report to an auditor. See Field-Level Security / PII Access and User Access Matrix.
• Does MetaSync work with Confluence Data Center or Server? — No. MetaSync is a Forge Cloud app, so it runs only on Confluence Cloud. There is no Data Center / Server build.
• How is PII handled? — MetaSync documents metadata, not record data — it never reads your business records (Custom Metadata Type records are the one exception — see The one exception: Custom Metadata Type records). Where your org uses Salesforce Data Classification, MetaSync surfaces field PII/sensitivity badges on pages and in reports so you can see which fields are classified. See PII & data classification and Field-Level Security / PII Access.
• How do I uninstall cleanly? — Just uninstall MetaSync from Manage apps. A preUninstall routine automatically purges all stored credentials, tokens, snapshots, history and configuration from Forge storage before removal. The Confluence pages MetaSync published are not deleted — remove any you no longer want yourself. See Permissions, scopes & data handling.
• Where are the tutorial videos? — At the top of every Documentation topic. Seven chapters — an eight-minute connection walkthrough covering both connection methods, and six chapters of one to two minutes each — walk from connecting an org to the governance reports; each topic shows the chapter that fits it best, and the rest of the set is a click away in What is MetaSync?. The videos are bundled with the app and play from the same place the app itself loads from, so no third-party video service is involved and no new permission is requested. Until an org is connected, the connect-and-first-sync chapter also plays on the dashboard.
• Why does Salesforce say redirect_uri_mismatch when I open the login? — Salesforce found your app from the Consumer Key, but MetaSync’s Callback URL is not on that app’s callback list yet — usually it was pasted into a similarly named app, or saved moments ago and not yet honoured. Add it to the app whose Consumer Key you used, save, wait a minute and try again. Every login-time error is covered in The Salesforce login fails or shows an error.

Note — Didn’t find your answer?. Start troubleshooting from the symptom: a slow or partial run → Sync appears stuck or partial; a login or callback error while connecting → The Salesforce login fails or shows an error; a connection that worked and then stopped → Re-authorizing your Salesforce org; changing which org is connected → Switching to a different Salesforce org; API errors → Rate limits & API errors; a missing component → Why is a component or type missing?. For the basics, revisit What is MetaSync? and Onboarding: from install to first sync.