Troubleshooting

When a flow does not behave the way you expect, the browser console is almost always where the answer is. Tracya logs a clear, prefixed message for every problem it runs into, so open your browser's developer tools, look at the Console tab, and filter for [Tracya]. This page covers what those messages mean and how to fix them.

The flow does not appear at all

The most common cause is the least alarming: you have already seen it. A First visit only flow shows once and then never again on that browser. To test it repeatedly, open your app in a private window, or clear your site data, or call Tracya.resetAll() from the console to wipe the seen state.

If that is not it, work down this list:

Is the flow published and active? A flow only reaches your users once you click Publish flow, and only while its status is Active in the Flow Manager. A draft or deactivated flow never shows.

Is the snippet on the page? Check that the two script tags are present, and that Tracya.init runs. If the console shows nothing from [Tracya] at all, the widget is not loading, and the problem is the snippet or how it is included.

Does the trigger match this page? If the flow has a Show on page path set, it only appears on that exact path. If it uses New users only, the window may have passed for this browser.

"Domain is not authorized for this project"

You set an allowed-domains list on the project, and the site currently loading the widget is not on it. The widget refuses to load flows and logs this message. Either add the current domain under Allowed domains in the Projects tab, or remove the restriction entirely to load everywhere. Remember that a wildcard like *.example.com covers subdomains but must be entered as such.

"Missing projectId in config"

Tracya.init was called without a projectId. Check that the value is actually present in your snippet and not an empty string or a template placeholder your backend failed to fill in.

"Element not found, step skipped"

A step points at an element that is not on the page when the step tries to show, so Tracya skips it and moves to the next one. This usually means one of three things: the element's selector changed since you built the step, the element loads later than the widget runs, or the step belongs on a different page than the one being viewed.

Rebuild the step by selecting the element again, so Tracya captures a fresh selector. If the element appears only after some delay or user action, consider whether that step suits the page it is on. Tooltips and highlights need their target present; modals and banners do not, since they are not anchored to an element.

The flow shows but looks wrong

If the styling is off, the theme is the place to look. Open Customize theme for the project and check the colours for the component type in question. Remember that each component, tooltip, modal, highlight, and banner, is themed separately, so fixing the tooltip does not touch the banner.

If a step's card is escaping its container or clipped, custom CSS on your own page may be interfering. The Custom CSS box in the theme editor can override specific styles to compensate.

Nothing loads and the console mentions CSP

If your site sends a Content Security Policy, it must allow the widget's script and its calls to the API. Both script-src and connect-src need to include https://api.tracya.io. A CSP violation shows in the console as a distinct message from the browser, separate from Tracya's own logs. The Installation page has the exact directives.

"init() already called, ignored"

Tracya.init ran twice. The widget uses the first configuration and ignores the second, so this is harmless, but it usually means the snippet is included on the page more than once. Worth removing the duplicate, so it does not cause confusion later.

Still stuck

If a flow misbehaves in a way none of this explains, the console log with the [Tracya] prefix is the thing to capture. It names the flow, the step, or the config value involved, which is usually enough to point straight at the cause.