Reference

Troubleshooting & FAQ

The questions that come up most, and the honest answers.

I don't see any events

Start with pharen verify — it checks the whole chain (key present and well-formed, the right ring for the build configuration, no value truncated by the xcconfig // rule, the config file actually wired, the Info.plist entry present, and whether the key has since been revoked) and names what's wrong instead of leaving you to guess. Add --wait and it will sit and watch for the first event.

If you'd rather check by hand, it's almost always one of three things:

  • The ingest key is missing or a placeholder. If PharenIngestKey isn't set to a real key, the SDK stays completely off — it's the intended way to disable Pharen in local builds. Set a real phi_test_… / phi_live_… value.
  • The purpose isn't granted. Consent is opt-in, so a started SDK with no purposes drops every event. Crashes need telemetry; sessions and track() events need behavioral. Grant them via PharenConsentGranted or at runtime. In a Debug build, the SDK prints a warning at start when nothing is granted — check the console.
  • You're looking at the wrong environment. A Debug build carrying your phi_test_… key lands in development, not production. Confirm which ring you're viewing.

My test crash didn't show up

  • Relaunch the app. Fatal crashes are written at crash time and uploaded on the next launch — the crash won't appear until you reopen the app once.
  • Run on a device, without the debugger. An attached debugger intercepts the signal before Pharen's handler sees it. Launch the app from the home screen, not from Xcode's run button.
  • Check telemetry consent. Without it, crash reports are kept on disk (not discarded) and upload once consent exists — so they may be waiting rather than lost.

Crashes aren't symbolicated

Unsymbolicated crashes mean Pharen doesn't have the build's dSYMs. Upload them — with the fastlane plugin, the Xcode run script, or pharen upload-symbols directly — and confirm your Release configuration keeps DEBUG_INFORMATION_FORMAT = dwarf-with-dsym.

Is it safe to re-run an upload or retry?

Yes — always. Symbols deduplicate by debug id (a re-run reports “already present” and exits cleanly). Builds, events, and crashes deduplicate by id on the server, so a retried upload, a relaunch that re-sends a queued event, or a crash report that takes several launches to get through are each counted once. There is nothing to reset between runs.

The CLI printed “using API …”

That's PHAREN_API_URL announcing an active override. It exists only for platform development; unset it to target the default control plane. The notice is deliberate — a stale override should never silently redirect a run.

Where do my key and token come from?

Your account is provisioned when we onboard your team (contact us). After that you issue your own ingest keys: pharen setup ios (or pharen init ios --mint on its own) mints one per environment and writes them into your build settings, so you never handle the value. They're public by design — commit them.

Your control credential is the secret one, and the two must not be confused. pharen auth login signs you in from a browser and stores a session, which is the path to prefer; PHAREN_AUTH_TOKEN is for CI environments. Either way it never belongs in source, and never in a build setting.

Why the split? An ingest key is write-only and ships inside your binary, so it can create data and read none. The control credential can read your data and mint keys, so it stays with the person or the CI job that holds it.

A key leaked — what do I do?

If it's an ingest key, first: that is probably fine. One ships inside every copy of your binary by design, and someone holding it can write junk events into one app in one environment and read nothing. If you want it replaced anyway, pharen ingest-keys rotate mints a replacement and expires the old key after a grace window, so builds already in the field keep working while you ship a new one. pharen ingest-keys revoke is the immediate, no-undo version — it stops every build carrying that key, right now.

If it's your control credential or a query key, treat it as a real leak and revoke it. Full details on all three, and which lever to reach for: Keys & credentials.