Using the Sync Engine Visualizer

The Sync Engine Visualizer shows you what the sync engine believes about every org: which Snowflake and Sigma resources it thinks exist, which it thinks are healthy, and which it knows have failed. This article explains how to read it, what every button does, and, just as importantly, what it cannot tell you.

Where: cloud-api.seekinsights.com/config/sync/overview. You'll need the global admin API key to log in; your browser can save it after the first visit.

The one rule (read this even if you skip everything else)

A red badge tells you something in that org failed. It does not tell you what, and it does not mean your app is affected.

The red number counts every failed resource in the org, across every app installed in it. In practice most of those failures are old, belong to apps you are not troubleshooting, and will never clear on their own. An org can sit at red 15 indefinitely while the app you care about runs perfectly.

So the rule is: read the red before you act on it.

  1. Find out what is actually red. The visualizer cannot list failures for you (see "What this tool cannot tell you"). Use the SF_GRANT_TO_ROLE_STATE table via the Sigma prod replica, filtered to your org and state = failed.

  2. Decide whether it is yours. If every failed row is a READER role, or targets a different app's tables, your run failure is somewhere else and retrying will not help you.

  3. If it is yours, retry. If it is not, leave it and keep diagnosing.

Then the retry sequence:

  1. Click the org node, then click Retry failed resources in the side panel.

  2. The item stays red until the engine actually gets to the retry. That's normal. When the retry happens, it turns yellow (TRANSIENT). Click Refresh (top of the page) if the graph doesn't seem to be updating; it's a snapshot, not live.

  3. Yellow is your cue: go run the variant. The item stays yellow until the next run; the run itself is what completes the remaining work.

  4. If the run succeeds, the item turns green (SYNCED).

  5. Confirm in the state table that your specific item flipped. Do not use the badge colour as confirmation. The org may still be red because of unrelated items even when your grant is now fine.

Red again after a retry means either the underlying problem still exists, or those items are stale records pointing at things that no longer exist. Stale records will go red every single time you retry them. Follow Troubleshooting App Installs & Runs, or report them for cleanup.

Reading the graph

Every colored number on a node is a count of resources in that state. The color tells you the state, and the position on the node is always the same:

Color State Position on node Meaning

🔴 Red

FAILED

top-left

Engine tried 3 times, gave up. Needs a human.

⚪ Grey

PENDING

top-center

Queued; engine hasn't gotten to it yet.

🟡 Yellow

TRANSIENT

top-right

In flight: the engine is working on it, or a retried item is waiting for the next variant run to complete the work.

🔵 Blue

OBSERVED

bottom-left

Reality drifted from what's expected. The next cycle fixes it, but only if something re-observes the resource. See the caution below.

🟢 Green

SYNCED

bottom-right

The engine successfully did the work and has not re-checked since. Not a guarantee that it is still true. See the caution below.

⚠️ What green actually means

SYNCED means "the engine did this successfully at the time, and has not looked again." It is a record of a past success, not a live health check.

If a grant is destroyed after the engine records it (most commonly because a proxy role was recreated), the record stays green permanently. Nothing turns red. Nothing shows up to retry. Meanwhile the app fails on a permission error and every tool on this page says the org is fine.

When a run fails on a permission error and this tool shows nothing wrong, check Snowflake directly. Troubleshooting App Installs & Runs Step 4 has the three commands.

⚠️ Why blue does not always self-heal

Drift is only corrected once something observes it. A SYNCED resource in a quiet org is not routinely re-observed, so drift that nobody looks for can sit undetected indefinitely. Observe External Resources is the mechanism that finds it, and it is currently unreliable (see below).

Two other things that confuse everyone at first

  1. The org's red count includes permissions (grants), not just the resources you can see. So the org can show red 15 while every category on the right (Warehouses, Roles, etc.) shows green. The failures are usually grants, which don't live in any category list.

  2. Clicking a category opens a list panel. Clicking an item in the list "plucks" it into the graph so you can inspect it. You rarely need this for the red-badge workflow.

What this tool cannot tell you

Worth knowing up front, so you don't spend an afternoon expecting answers it doesn't have.

  • Which resources are failing. The badge counts them; nothing here lists them. Grants belong to no category, so you either pluck nodes one at a time or query SF_GRANT_TO_ROLE_STATE.

  • Whether a green item is still true. See above. Green is a memory, not a measurement.

  • Anything in a database the sync engine does not manage. Hand-built shared tables and hand-applied roles are completely invisible here. There is no record of them to be green or red.

  • Whether a proxy role has SELECT on its table. That layer is maintained by D&A outside the engine and does not appear anywhere on this page. It is a common cause of run failures.

  • Who changed something, or when. Snowflake's ACCOUNT_USAGE.QUERY_HISTORY is the only place that answers this.

Every button, what it does, and how safe it is

Safe anytime (read-only)

Refresh (top of page) reloads the data for the orgs you have open. It changes nothing in the backend. Use it whenever the page seems stale, especially while waiting for red to turn yellow. Note: it only works after you've opened at least one org.

Auto (next to Refresh) turns on auto-refresh every 30 seconds. The ring around the button is the countdown. Same safety as Refresh: purely read-only. Turn it on while you're waiting on a retry.

Org-level actions (side panel, after clicking an org)

Retry failed resources takes everything red in that org and queues it for the engine to try again. Items stay red until the engine reaches them, turn yellow (TRANSIENT) when the retry happens, and turn green only after the next successful variant run completes the work.

This is your main button, with two limits worth knowing:

  • It only acts on things marked FAILED. If your problem is a grant the engine believes is fine, this button does nothing at all.

  • It retries everything red in the org, including stale records for apps and versions that no longer exist. Those will fail again immediately, which can look like your fix didn't work when it did.

Trigger resource sync tells the engine to re-check this one org right now instead of waiting for its normal triggers. Use it after a fix or a retry if things seem slow to pick up. Scoped to one org, so it's low-risk.

Global actions (header): use sparingly

Trigger Global Sync re-checks every org on the platform. Only one sync runs at a time platform-wide, so a global run can hold up everything behind it. Don't use this for a single-org problem; use Trigger resource sync on that org instead.

Observe External Resources makes the engine walk all of Snowflake to detect drift: things that changed behind the engine's back. It is the only mechanism that finds a grant which vanished after being recorded as SYNCED, which makes it more important than its "heavy button" reputation suggests.

It is also the most expensive button on the page, and it is currently fragile: a single failure partway through can discard the entire sweep, including work that already succeeded. Do not run it yourself. If you believe something is green that shouldn't be, report it with your evidence and let engineering decide.

Before either global button: check whether a sync is already running. If the engine is visibly backed up with pending items, adding more work makes everyone's day worse.

Quick answers

Why does my run keep failing even though I keep rerunning it? Reruns don't fix failed permissions. But before assuming the red badge is your answer, check what is actually red. If the failures belong to other apps, the badge is a coincidence and your cause is elsewhere.

I clicked Retry and it's still red. Expected at first: items stay red until the engine actually reaches the retry, and the graph is a snapshot. Click Refresh or turn on Auto. If it goes yellow then red again with the same error, the retry cannot fix it: either the underlying cause is unfixed, or those are stale records that will always fail.

It's been yellow for a while and nothing is happening. Yellow waits for the next variant run; the run is what finishes the work. Run the variant; don't wait for green first.

The red came back after my retry. Two possibilities. Either the underlying cause hasn't been fixed (usually a dropped permission), or those items are stale records naming roles and tables that no longer exist. Check the error text in the state table to tell which. Stale records need cleanup, not retries.

Everything is green but the app still fails. Do not conclude it isn't a permission problem. Green means the engine hasn't re-checked, not that the grant still exists. If the error names a table and says "does not exist or not authorized," check Snowflake directly with Troubleshooting App Installs & Runs Step 4. If the grants genuinely are in place, then look at upstream data timing, a version mismatch, or an infrastructure blip.

The org is red but the app I care about runs fine. Is that normal? Yes, and it is common. Old failures for other apps accumulate and never clear. Do not block runs on the badge alone.

How do I know which resources are failing? Not from this page. Query SF_GRANT_TO_ROLE_STATE filtered to your org.

Related articles