Troubleshooting

The Display tab’s “Runtime diagnostics” + Simulator are the fastest debugging tools. This page covers reading them and standard checks for common issues.

Diagnostic panel (from Display StickyBar)

Subtitle: “Based on Simulator preview, not actual storefront data.”

8 diagnostic reasons (from i18n diagnostics.reason.*)

Reason	Meaning	Fix direction
Visible	All good	—
Page type mismatch: this widget targets {expected} pages, visitor is on {got}.	Widget mount page ≠ visitor page	Check Placement and Pages dimensions, or adjust Simulator URL
Blocked by display rule	A visibility dimension didn’t match	Switch through 9 dimensions or check Simulator verdict per dimension
No available placement on this page	Theme has no available anchor on this page	Switch theme, switch placement, or use Custom Position
Page rule no match	Pages dimension filtered out	Add current page type to Include list
Visitor login state doesn’t match	Customers dimension filtered out	Check Login state setting
Placement not set	Placement required field missing	Pick a mount location
Invalid CSS selector	Hide theme elements dimension (Pro) has invalid selector	Fix CSS selector syntax

Image: diagnostic modal (8 reasons, 1 screenshot each)

Collect-all trace

The new version lists all failing dimensions at once — fix in one pass:

• Single failure → shows that reason (e.g. “Page rule no match”)
• Multiple failures → list view with each fail’s detail (dimension name + reason code)
• All pass → “Visible”

Simulator

Display tab right sidebar — fill virtual customer profile to see hits:

• URL — auto-parses page type + UTM
• Device / Login state / Country (segmented control)
• Customer tags / Total spent / Order count (input)

Switch persona to see verdict change in real time without affecting saving.

Standard checklist: “Widget published but not showing on storefront”

In order:

1. Is app embed enabled?

Go to Widget list → StatsRow → “App status” card:

• “Enabled” ✓
• “Disabled” — “App embed not enabled; widget won’t render on storefront.” Click “Enable” to jump to theme editor
• ⚠️ “Switching themes resets this toggle — re-enable after changing themes.”

2. Check diagnostic panel verdict

Open widget editor → Display tab → top StickyBar or diagnostic button → see which reasons fail.

3. Verify with Simulator

In the right Simulator sidebar paste a real link (with utm params, etc.) to check verdict.

4. Check browser console

widget.js outputs error prefix [tt-blocks], common messages:

• [tt-blocks] mount failed: {widgetId} reason: ... — mount failed
• [tt-blocks] visibility eval blocked: {dimension} — dimension short-circuited
• Theme JS conflicts may show as jQuery / Theme JS errors

Read window.__TTB_DIAGNOSTICS__[widgetId] directly in browser console for full diagnostic state.

5. Custom Position scenarios

If using Custom Position:

• Confirm theme editor’s manual block is added with correct widget ID pasted
• Confirm theme is saved
• Confirm manual block is on a published template (not draft)

6. Contact support

Email with:

• Widget ID (Copy ID button on widget list card)
• Storefront URL
• Browser and OS version
• Console screenshot
• Expected vs actual behavior

Limits and quotas

Limit	Value	Trigger behavior
Single widget config size	96 KiB	Save fails, editor shows friendly toast (D1 metafield raw stack 128 KiB)
customAnchorSelectors per widget	24 entries	Excess ignored
Shopify checkout block	≤ 1 per shop	Shopify platform limit
Free demo quota (products / variants etc.)	See Plans	Exceeding shows upgrade prompt
Stats data retention	Last 90 days	Auto-cleared after

Common errors

”Save failed” / “Widget too large”

• widget config exceeds 96 KiB
• Check for overly long CSS or many duplicate components
• Split into multiple widgets (visibility config can achieve same effect)

“Free quota used up”

products / variants etc. dimension exceeds demo quota.

• Reduce config items → or upgrade Pro for unlimited
• See Billing tier

”Cross-type switch not allowed”

label widget anchor can’t change to non-label, vice versa (see Widget types).

• To change type → rebuild a new widget

Widget loading mechanism (brief)

Useful for troubleshooting:

Shopify theme loads widget.liquid
  ↓ Inject window.__TTB_BLOCKS__ = { widgetId: config }
  ↓ Load widget.js (async)
widget.js scans after DOMContentLoaded:
  ├─ Manual: find .ttb-block-wrapper[data-widget-id] in DOM
  └─ Auto: iterate __TTB_BLOCKS__ for placement.mode === "auto"
              ↓ Cascade through theme DOM anchors
              ↓ Found → create wrapper → mount
              ↓ Not found → no mount, diagnostic written to __TTB_DIAGNOSTICS__
Pre-mount evaluator runs visibility 9 dimensions
  ↓ All pass → mount and render
  ↓ Any fail → no mount, diagnostic written to __TTB_DIAGNOSTICS__

See Storefront behavior.