Troubleshooting

Updated

Start with the client's doctor command in your NativePHP app. It checks configuration, reachability and registration in that order and stops at the first failure:

php artisan telltale:doctor

Then check the app's Recent ingest health on the Telltale dashboard, or ask your agent to run ingest_health.

Doctor messages

"Telltale configuration is incomplete or invalid." TELLTALE_URL is missing or is not an http or https URL, or TELLTALE_INGEST is empty. Set both in the build environment you are running.

"The Telltale server could not be reached." The URL is wrong, the domain does not resolve, or the request timed out. Check that the URL is the stable public address of your deployment.

"The Telltale server is not healthy." The server answered with a 5xx error. Check the deployment in Laravel Cloud.

"Registration failed. Check the configured server and ingest value." The server rejected the ingest value. Usually the value was mistyped, belongs to a different app or deployment, or has been rotated. Rotate it on the dashboard and use the new value.

Nothing arrives, but doctor passes

Mobile only uploads while the app runs. There is no background upload; events wait in the outbox until the app's queue worker drains it.
The queue connection is sync or unset. Draining is queued; with a sync connection no drain job is dispatched.
The user opted out. After Telltale::optOut() nothing is captured or sent.
A beforeSend callback returns null. Those events are dropped before they reach the outbox.
Automatic capture is turned off with capture.enabled. Only your own Telltale::event() calls are recorded.

Ingest responses

Status	Message	Cause
`401`	Invalid credentials.	Wrong or rotated ingest value at registration, or an install token that is unknown, deleted or revoked. The client clears its token and tries to register again.
`413`	Request body is too large.	The body exceeds `TELLTALE_MAX_BODY_BYTES`.
`415`	Content encoding is not supported.	Only `gzip` or no encoding is accepted.
`422`	A batch may contain at most 100 events.	The client's `batch_size` is larger than the server's batch limit.
`422`	Envelope version N is newer than this server supports.	The client is newer than the server. Upgrade your Telltale fork.
`429`	Too many requests.	A per-IP, per-app or per-install rate limit. The response carries `Retry-After`.
`429`	Daily event volume exceeded.	The app's or install's daily event cap for the current UTC day is reached.
`503`	Ingest is unavailable due to invalid server configuration.	A server limit variable is set to something other than a positive integer. Fix or remove it.

Clients retry with exponential backoff, so short spells of 429 resolve on their own. Persistent rate-limit hits or rejections show on the dashboard's ingest health panel.

One device stopped reporting

If you revoked its install, it stays revoked: it cannot send or register again under the same install UUID. A fresh install of the app on that device generates a new UUID and registers normally.

Client-reported drops are rising

Devices are discarding events before delivery because the outbox reached 10,000 rows or held events longer than 30 days. That points to devices that rarely get a chance to drain, such as mobile apps that are rarely opened while online, or to delivery failing repeatedly.

Older data is missing from some answers

Raw events older than the retention window (90 days by default) are pruned daily. Funnels, screen flow, error lists and timelines read raw events, so they cannot look further back. Active users, release adoption, event counts, retention and sessions do not depend on raw events and still can.

A crash is not in Telltale

Telltale v1 records PHP errors that reach Laravel's exception handler. Native crashes, out-of-memory kills, ANRs, Electron Crashpad reports, SuperNative screen exceptions and mobile AsyncTask failures are not captured.

The dashboard shows only 100 apps

The app list and the apps tool both return up to 100 apps.