Reference

Troubleshooting & FAQ

Start with the symptom you see. Check the build and environment for missing events, then verify consent, matching symbols, or credential scope as needed.

I don't see any events

Start with pharen verify — it checks the whole chain (key present and well-formed, the right environment 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 PharenConsentGrantedAtBuild 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 live. Confirm which environment you're viewing.

My test crash didn't show up

  • Relaunch the app. The SDK attempts to upload a saved fatal crash report when the app next launches.
  • 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. Grant it before the test crash and keep it granted when you relaunch.

Ready to move beyond evaluation? Organization approval unlocks test and live keys and uploads of matching dSYMs for readable crash stacks. Your paid plan determines which features and usage limits apply. Go to organization approval.

Crashes aren't symbolicated

Check that Pharen has dSYMs matching the affected binary's debug ID. Upload the matching symbols — with the fastlane plugin, the Xcode run script, or pharen symbols upload directly — and confirm your Release configuration keeps DEBUG_INFORMATION_FORMAT = dwarf-with-dsym.

Retrying uploads

Uploading matching symbols again reports “already present” when Pharen has their debug IDs. The server deduplicates retried events and crash reports by ID. Running pharen builds upload again creates a new build record.

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 organization is created when your application is approved (start with Pharen). 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.

Email from Pharen isn't arriving

Pharen sends from two addresses. Notices about your organization and mail about your own access come from [email protected]. The email a member can switch on in the console about new reports comes from [email protected]. Both show as Pharen, and replies to either go to [email protected]. If your mail filters quarantine new senders, allow both addresses.

Regaining control of your organization

If no owner of your organization can act for your company — for example, your only owner has left it — write to [email protected]. We consider a request only with evidence that it comes from your company: proof that you control your company's domain, and an independent confirmation, such as a billing record we hold or a confirmation from an officer of your company. Evidence makes a request one we can consider; it does not by itself decide it.

If owners disagree, we do not choose between them; we may pause changes to your organization's members, credentials and billing while you resolve it, as the Terms provide. Your apps keep sending throughout.

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 --reason compromise is the immediate version — it stops every build carrying that key, right now, and the key is never restored. A revoke without that reason is routine: the builds are held, and an owner can restore the key for thirty days.

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.

My agent's number disagrees with the console

Compare the app, environment, release track, time window, and grouping against the request shown in the console. A local build using a live key reports to live, while customer metrics default to the released track. Grouped results can also withhold small counts. Check for unconfirmed builds before interpreting a zero released count.

My MCP client cannot send a header

A query-key connection requires Authorization: Bearer <query key>. If your client supports browser approval, follow that setup in Connect your agent; if yours is not among them, tell us which one.