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 keeps these failures out of the user’s path (per the dual-send philosophy: don’t break the user’s checkout because Google had a hiccup).

For the server tracker, debug only controls the console.warn. The same failure is always captured on the structured return value (result.ga4.error / result.ads.error) so you can route it to your own observability without enabling debug. For the browser tracker, gtag failures are still swallowed silently when debug: false.

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.

For the server tracker, “swallowed” only refers to the absence of a log. The structured return value still carries the failure, so you can route it to your own observability:

const result = await serverTracker.trackConversion({ /* ... */ });
if (!result.ads.ok) reportError(result.ads.error);

For the browser tracker, gtag failures truly are swallowed when debug: false — they don’t surface anywhere. If you need visibility there, wrap window.gtag yourself.

For the server side, your runtime’s request logging plus the structured result give you visibility without ever needing to flip debug on in production.

See also

Section titled “See also”