Skip to content
trackbridge

Debug mode & the warning catalog

Trackbridge has two classes of console warnings, gated differently:

ClassGated byExamples
Developer warningsAlways onAuto-generated transactionId.
API failure warningsOnly when debug: trueGtag exception, GA4 MP non-2xx, Ads API non-2xx, network error.

The split reflects a value judgment about who needs to know: programming mistakes are loud, infrastructure failures are quiet by default.

Class 1: developer warnings (always on)

Section titled “Class 1: developer warnings (always on)”

These fire whether or not debug is set. The scenario they cover is a programming mistake that breaks an SDK invariant. You want to know about these in development and in production — they indicate code that won’t behave correctly even if everything around the SDK is fine.

There is currently one warning in this class: the auto-transactionId warning. It fires on every trackConversion call where transactionId is missing or empty:

[trackbridge] ⚠️ trackConversion called without transactionId
  → Auto-generated: tb_a8f3c1d2-...
  → Dual-send disabled for this call. Pass a transactionId you control
    to enable cross-side dedup.
  → See: trackbridge.dev/docs/dedup

It is loud on purpose. Silently auto-generating a UUID would make the conversion appear to work while quietly disabling the dedup contract — and that’s the worst failure mode. See Deduplication & transactionId for why.

Class 2: API failure warnings (debug-gated)

Section titled “Class 2: API failure warnings (debug-gated)”

These fire only when you pass debug: true to the tracker constructor:

const tracker = createBrowserTracker({
  // ...
  debug: process.env.NODE_ENV !== 'production',
});

These warn about transient infrastructure problems: network errors, gtag exceptions, non-2xx HTTP responses from Google. In development, you want them — they tell you that a call you made didn’t reach Google. In production, you usually don’t want them — your customers don’t run with DevTools open, and the SDK already swallows the underlying failure (per the dual-send philosophy: don’t break the user’s checkout because Google had a hiccup).

The warnings in this class:

  • Gtag event exception (browser).
  • Gtag conversion exception (browser).
  • GA4 Measurement Protocol non-2xx (server).
  • GA4 Measurement Protocol network error (server).
  • Google Ads API non-2xx (server). Includes the response body so you can see what Google rejected.
  • Google Ads API network error (server).

Full text and trigger conditions on the Warning catalog page.

Section titled “Recommended setup”
debug: process.env.NODE_ENV !== 'production',

That’s it. Loud locally, quiet in production. If you want a different policy — for example, debug on a staging deployment but not on dev or prod — just route the boolean however you need.

What “swallowed” means in production

Section titled “What “swallowed” means in production”

When debug: false and an API call fails, the SDK does not throw and does not log. The Promise from trackConversion resolves successfully. The user sees no error. The conversion is lost — but the dual-send pattern means the other side likely caught it.

This is intentional. The alternatives — throwing, logging unconditionally — both make tracking failures visible to users in ways they shouldn’t be. Tracking is supplementary to the user’s actual transaction. It must not break the checkout.

If you need to know about production-time failures (you do, eventually), surface them in your own observability:

const tracker = createBrowserTracker({
  // ...
  debug: false,
});


try {
  await tracker.trackConversion({ /* ... */ });
} catch (err) {
  // Won't trigger — Trackbridge doesn't throw — but if you wrap
  // the call in your own instrumentation, this is where it goes.
}


// Better: wrap window.gtag yourself or watch for failures from
// your own server-side calls and ship them to your monitoring.

For the server side, your runtime’s request logging already captures the underlying HTTPS responses. With debug: true on staging and proper server logging in prod, you have visibility either way.

See also

Section titled “See also”