Troubleshooting

Troubleshooting

Common issues and fixes when using tremor-client-java.

---

Invalid baseUrl

Symptom

IllegalArgumentException: baseUrl must be a valid absolute URL

Cause

The client requires an absolute URL such as http://localhost:8080/tremor or https://tremor.example.com/tremor.

Fix

String tremorKey = "...";

TremorClient.builder(tremorKey).baseUrl("http://localhost:8080/tremor").build();
TremorClient.builder(tremorKey).baseUrl("https://tremor.example.com/tremor").build();

Do not pass a relative path such as /tremor.

---

Missing Client Key

Symptom

IllegalArgumentException: apiKey is required

Cause

The key passed into TremorClient is blank or missing.

Fix

TremorClient.builder(tremorKey).baseUrl("http://localhost:8080/tremor").build();

---

401 or 403 from Tremor

Symptom

TremorApiException with an authentication or authorization status code.

Causes

• wrong Tremor key
• wrong Tremor environment
• request sent to the wrong server

Fixes

• verify the key you passed into TremorClient
• verify the Tremor base URL
• verify the final request target is /tremor/api/v1/ingest

If you catch TremorApiException, inspect getStatusCode(), getResponseBody(), and getUrl().

---

Response missing fingerprint

Symptom

TremorSerializationException: Tremor response did not include a fingerprint

Cause

The server returned success without the expected response body shape.

Fix

Check the Tremor server response body. The client expects a success response shaped like:

{"fingerprint":"abc123"}

---

Validation failure before send

Symptom

IllegalArgumentException thrown before any HTTP request is observed.

Common causes

• error is missing
• error.className is blank
• error.message is blank
• too many tags
• too many breadcrumbs
• userCustomData is too deeply nested

Fix

Start from the smallest valid event and add fields incrementally:

TremorEvent event = TremorEvent.builder()
    .error(
        TremorError.builder()
            .className("java.lang.IllegalStateException")
            .message("checkout failed")
            .build())
    .build();

---

Shared OkHttpClient got shut down

Symptom

Other parts of the application start failing after closing the Tremor client.

Cause

This usually means the application shut down its own shared OkHttpClient, not TremorClient.

Fix

Pass the shared OkHttpClient into TremorClient and manage its lifecycle at the application level:

OkHttpClient shared = new OkHttpClient();
String tremorKey = "...";
TremorClient client =
    TremorClient.builder(tremorKey)
        .baseUrl("https://tremor.example.com/tremor")
        .httpClient(shared)
        .build();

TremorClient.close() does not shut down a caller-provided client.

---

reportAndSuppress hides the original failure

Symptom

The application continues running and no exception reaches the caller.

Cause

That is the intended behavior of reportAndSuppress(...).

Fix

Use send(...) when you want reporting without swallowing the original failure.

Use reportAndSuppress(...) only for best-effort paths such as background jobs, metrics, or non-critical refresh work.