Troubleshoot

The Encatch Web SDK includes a built-in Debug Mode to help you track down installation, targeting, and form-display issues. When activated, the SDK writes diagnostic messages to your browser console so you can see whether the client loaded, whether users are identified, and whether API calls succeed.

For publishable key, allowed domains, CSP, and init timing, see Troubleshoot installation.

Debug Mode

When Debug Mode is on, Encatch emits extra console.warn messages prefixed with [Encatch], [IFRAME-MANAGER], [EVENT-HANDLER], or [Encatch API]. Use these logs together with the checks in Debug Panel below to confirm your installation is healthy.

Encatch does not show a floating on-page debug overlay. Inspect state in DevTools and subscribe to form events with _encatch.on() instead.

Activate Debug Mode

The simplest way to enable Debug Mode is to pass debugMode: true when you call init():

import { _encatch } from '@encatch/web-sdk';

_encatch.init('your-publishable-sdk-key', {
  debugMode: true,
});

CDN / script tag:

<script>
  _encatch.init('your-publishable-sdk-key', { debugMode: true });
</script>

You can also enable Debug Mode from the browser console after init() has run on the current page:

window._encatch._config.debugMode = true;

Debug Mode stays active for the rest of that page session (until you reload or close the tab). It is useful while debugging SPA navigation or automatic triggers on the same page. After a full page reload, pass debugMode: true in init() again — a console toggle does not persist across reloads.

To disable Debug Mode on the current page:

window._encatch._config.debugMode = false;

Or pass debugMode: false (the default) on your first init() call when the page loads. A second init() is ignored — Encatch logs [Encatch] SDK already initialized. Ignoring init call. and does not change config.

Debug Panel

Encatch does not render a visual debug panel in the corner of the browser. Use the following DevTools checks as your debug panel — they tell you whether the client installed correctly, whether you are identifying users, and whether the remote SDK loaded.

1. Confirm the SDK is on the page

typeof window._encatch
// Expected: "object"

2. Confirm init() ran

window._encatch._initialized
// Expected: true

3. Check identification mode

localStorage.getItem('encatch_user_name')
// null → anonymous (Visitors targeting)
// non-null string → identified after a successful identifyUser() (Logged-in Users targeting)

4. Subscribe to form lifecycle events

const off = _encatch.on((eventType, payload) => {
  console.log('[Encatch event]', eventType, payload);
});
// Later: off();

5. Confirm the remote SDK script loaded

After init(), Encatch injects https://form.encatch.com/s/sdk/v1/encatch.js. In Network, filter for encatch.js and confirm status 200.

If checks 1–2 pass but no requests reach api.encatch.com, reload the page and try again. If it still fails, see Debug Tip #1 below.

Debug Logs

In addition to the checks above, enabling Debug Mode generates detailed logs in the browser console.

Open Developer Tools → Console:

Filter by Encatch to narrow results.

What Debug Mode logs

Messages that can appear even when Debug Mode is off

When contacting support, a screenshot of the Console and Network tabs is helpful — redact X-Api-Key and any signature headers first.

Troubleshooting Tips

Debug Tip #1: Check if SDK is loaded

If forms do not appear and you see no Encatch logs, the client was most likely not loaded into your page.

Open the Elements tab in Developer Tools and search for encatch. With the CDN / Script Tag method you should see a jsDelivr script tag. With the NPM Package method, the stub is bundled into your app JavaScript.

In the Console, confirm:

window._encatch?._initialized === true

If this is false or window._encatch is undefined, verify your install steps and that init() runs in the browser — not during server-side rendering.

Debug Tip #2: Test with a newly opened Incognito Window

The Encatch Web SDK uses localStorage to persist device IDs, session state, and user identity between page loads. That cached state can affect whether a form shows again after you change targeting or throttling in the dashboard.

Always test Encatch in a newly opened Incognito / Private window when debugging targeting or throttling. Alternatively, call _encatch.clearAll() in the console (see Debug Tip #4).

Debug Tip #3: Check if you are using the audience type

The Web SDK runs in one of two modes:

When you can identify your users in code, Logged-in Users is the right audience choice.

When you cannot identify users — for example on a marketing site — enable Visitors.

Check your current mode in the console:

localStorage.getItem('encatch_user_name')

Also review country, device type, user language, and past interaction — any of these can prevent a form from launching.

Debug Tip #4: Reset user data in your account to start over

You will often want to test a feedback form again after you already completed or dismissed it. Dashboard rules such as throttling, response limit, and past interaction can block repeat views.

You have two ways to start with a blank slate:

1. Reset in the browser (fastest for local testing)

_encatch.clearAll();

This wipes persisted SDK data and stops background ping. Call startSession() or identifyUser() before testing automatic triggers again.

For logout flows — clear identity but keep the device:

_encatch.resetUser();

2. Reset in the Encatch dashboard

• Remove or filter out test responses in Reports for that form, or
• Relax throttling and past-interaction rules while testing.

In both cases, open a new Incognito window for further testing so no old browser state remains.

Debug Tip #5: Inspect network tab

Use Developer Tools → Network to inspect communication between your browser and Encatch servers.

Set the filter to Fetch/XHR and search for encatch or api.encatch.com. You should see requests such as:

The remote SDK script loads separately as a module script (not XHR): https://form.encatch.com/s/sdk/v1/encatch.js after init().

Successful responses return 200 or 201. Encatch returns 429 when rate limits are exceeded.

If any request returns a 4xx or 5xx error, click it and read the response body. For key, domain, session, and CSP issues, work through Troubleshoot installation.

trackEvent() and trackScreen() send no request until a device ID exists — call startSession() or identifyUser() first. This is expected behavior.

When contacting support, capture the status code and response body. Redact X-Api-Key and signature headers before sharing.

Related

• Installation — Troubleshoot installation
• Client Reference — clearAll(), resetUser(), session control, event subscriptions
• Content Security Policy
• Targeting