Troubleshooting & FAQ

Events Don't Show Up

1. Turn on debugMode: true in Analytics.configure and watch the Xcode console. Lines start with [Oddlytics].
2. Look for these messages:

Console message	Meaning
Warning: Analytics not configured. Call configure() first.	track ran before configure. Move configure earlier.
Dropping N events due to client error: 401	The apiKey doesn't match the Worker's AUTH_KEY.
Dropping N events due to client error: 400	An event broke a limit: a name, appId or session ID over 255 characters, metadata over 10 KB, or more than 100 events in one batch.
Server returned status: 5xx followed by Re-queued	The Worker failed. The events are retried with the next send.
Network error: ...	The device couldn't reach the Worker. Check the endpoint address.
Sent N events, status: 200	Delivered.

3. Watch the Worker's logs while you send events:

   cd packages/worker
   npx wrangler tail

"Unauthorized" When Tracking Events

Check that the secret is set with npx wrangler secret list, and that the key in your app matches it exactly.

"Database not found"

The database_id in packages/worker/wrangler.toml must match the ID that npx wrangler d1 create oddlytics-db printed.

The Dashboard Says "Failed to load analytics data"

• Check that NEXT_PUBLIC_API_URL points at your Worker, and rebuild the dashboard after changing it. The value is built into the files.
• Open the Worker's address in a browser. It should return {"status":"ok", ...}.
• Try curl https://<worker>/stats/overview.

Errors Mentioning a Missing Table

Messages like Table "event_aliases" missing. Run migrations. or Database schema out of date mean the database was created with an older schema. Apply the current one, as in Updating.

Renaming, Customizing or Deleting Fails

These need the API key. Make sure the dashboard was built with NEXT_PUBLIC_API_KEY set to the Worker's AUTH_KEY.

Does Oddlytics Work Without Cloudflare?

The Worker is written for Cloudflare Workers and D1, and the guides here only cover Cloudflare. The dashboard is static files and can be hosted anywhere, for example on Vercel.

Can I Send Events From Android or the Web?

Yes. Anything that can send JSON can call POST /track. Set platform to tell the platforms apart; the Worker stores iOS when it's missing.

How Much Does Cloudflare's Free Tier Cover?

At the time the deployment guide was written, the free tier included 100,000 Worker requests a day and, for D1, 5 GB of storage, 5 million reads a day and 100,000 writes a day. The Swift package sends events in batches, but each event is one database write. Check Cloudflare's current pricing, and see your usage with:

npx wrangler d1 info oddlytics-db