Warning catalog

The complete list of console.warn calls in the SDK. Two categories: always-on (developer warnings about programming mistakes) and debug-gated (infrastructure failures only surfaced when debug: true).

For the conceptual split, see Debug mode & the warning catalog.

Always-on warnings

These fire regardless of the debug flag. They indicate something the application code did wrong, not transient infrastructure trouble.

Auto-generated transactionId

[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


Source	Both `tracker.trackConversion()` and `serverTracker.trackConversion()`.
Trigger	`transactionId` is missing or empty on the call input.
What’s happening	The SDK falls back to a fresh UUID prefixed with `tb_`. The conversion still fires, but because the other side will generate a different fresh UUID, Google cannot deduplicate the two calls.
Fix	Pass a stable string as `transactionId` on both sides. Almost always your order ID. See Deduplication & transactionId.

Debug-gated warnings

These fire only when debug: true is set on the tracker constructor. In production with debug: false, the underlying failure is silently swallowed (the Promise resolves normally, no log).

Browser: gtag event exception

[trackbridge] gtag event failed: <error>


Source	`tracker.trackEvent()`.
Trigger	`window.gtag(...)` threw.
Likely cause	`window.gtag` is undefined (the gtag script hasn’t loaded yet, or a TagManager container isn’t present). Less commonly, gtag itself errored on the params shape.
Fix	Confirm gtag is loaded before the tracker fires. If you load gtag asynchronously, defer the first event until `dataLayer` is ready, or accept the dropped event.

Browser: gtag conversion exception

[trackbridge] gtag conversion failed: <error>


Source	`tracker.trackConversion()`.
Trigger	`window.gtag(...)` threw during the conversion push.
Likely cause	Same as above.
Fix	Same as above. The dual-send pattern means the server-side fire is your floor — a single failed gtag call doesn’t lose the conversion.

Server: GA4 Measurement Protocol non-2xx

[trackbridge] GA4 MP returned <status> <statusText>


Source	`serverTracker.trackEvent()`.
Trigger	The GA4 MP endpoint returned a non-2xx response.
Likely cause	Wrong `ga4ApiSecret`, wrong `ga4MeasurementId`, malformed `clientId`, or transient GA4 issue.
Fix	Confirm the secret in GA4 Admin → Data streams → Measurement Protocol API secrets matches `ga4ApiSecret`. Confirm the `clientId` is the third+fourth dot-separated segment of the `_ga` cookie value (`GA1.1.<clientId>.<timestamp>` → `<clientId>` is `<part3>.<part4>`).

Server: GA4 Measurement Protocol network error

[trackbridge] GA4 MP request failed: <error>


Source	`serverTracker.trackEvent()`.
Trigger	The HTTP request to GA4 failed before getting a response (DNS, connection reset, timeout).
Likely cause	Egress firewall, runtime networking misconfiguration, or transient outage.
Fix	Check egress rules; the SDK needs to reach `www.google-analytics.com` over HTTPS.

Server: Google Ads API non-2xx

[trackbridge] Ads API returned <status>
<response body>

The response body is logged as a separate argument so it’s expandable in DevTools.


Source	`serverTracker.trackConversion()`.
Trigger	The Ads API returned a non-2xx response.
Likely cause	Many — Google’s error responses include a `details` array that names the cause: `INVALID_DEVELOPER_TOKEN`, `USER_PERMISSION_DENIED`, `INVALID_CONVERSION_ACTION_RESOURCE_NAME`, etc.
Fix	Read the body. The most common causes: developer token still in test mode (request basic-access upgrade in Ads UI → API Center); customer ID has dashes (digits only); `loginCustomerId` missing for MCC hierarchies; conversion action belongs to a different customer than `customerId`. See Setting up Google Ads OAuth.

Server: Google Ads API network error

[trackbridge] Ads API request failed: <error>


Source	`serverTracker.trackConversion()`.
Trigger	The HTTP request to Ads API failed before getting a response.
Likely cause	Egress firewall, runtime networking misconfiguration, OAuth refresh failure (which throws separately — see below).
Fix	Check egress to `googleads.googleapis.com` and `oauth2.googleapis.com`.

Errors that throw (not warnings)

Two failure paths in the SDK throw rather than warn — they indicate misconfiguration that nothing later can recover from.

Init-time required field missing

Error: [trackbridge] adsConversionId is required
Error: [trackbridge] ga4MeasurementId is required
Error: [trackbridge] ga4ApiSecret is required

Throws at createBrowserTracker / createServerTracker. Fix: provide the field.

Server: trackConversion without ads config

Error: [trackbridge] trackConversion requires `ads` to be configured on createServerTracker

Throws at call time. Fix: pass ads: { ... } when creating the server tracker, or stop calling trackConversion from the server.

Server: unknown conversion label

Error: [trackbridge] no conversionAction configured for label "..." — add it to ads.conversionActions on createServerTracker

Throws at call time. Fix: add the label to your conversionActions map. See Mapping conversion actions.

Server: OAuth refresh failure

Error: [trackbridge] OAuth refresh failed with <status> <statusText>

Throws at call time when an Ads API call needs to refresh the access token and Google rejects the request. Fix: regenerate the refresh token via OAuth Playground; common cause is a personal-Google-account refresh token that’s been silently revoked.