# Troubleshoot Inspector

> Fix Inspector download, authorization and connection problems.

Find the symptom below and follow its steps. If the problem continues,
[contact support](#get-help).

## Download is unavailable

The install page validates the Nightly release manifest. It deliberately hides
installers when the manifest cannot be fetched, contains an invalid version,
has missing or extra artifacts, or includes an invalid SHA-256 value. Retry
later or contact support; do not construct a download URL manually.

## Installer verification fails

Download the artifact and its `SHA256SUMS` sidecar again, then compare the digest using the command on [Install](https://docs.polymorfa.com/testing/inspector/install). A mismatch means the file is incomplete or altered; delete it and do not launch it.

## An automatic macOS update does not finish

A failed update check does not interrupt your Inspector session. Finish any
work in progress, then quit and reopen Inspector to allow another check.

If an update download or relaunch still does not finish, use the manual
recovery path:

1. Download the latest Nightly DMG from [Install](https://docs.polymorfa.com/testing/inspector/install).
2. Verify the DMG against its `SHA256SUMS` sidecar.
3. Quit Inspector, open the DMG, and replace Polymorfa Inspector in
   Applications.
4. Open Inspector again.

Do not construct a download URL manually. If the install page is unavailable,
retry later or contact support.

## Device authorization does not complete

Inspector uses the browser device flow. Confirm that:

- You are signed in at [polymorfa.com/console](https://www.polymorfa.com/console).
- The device page shows the same user code as Inspector.
- You selected at least one team where you still have an active
  membership.
- The requesting app, location details, request time, teams, and active
  projects match what you expect.
- You explicitly approve the request before the code expires.
- Your browser allows credentialed requests to `api.polymorfa.com`.

Expired and completed codes cannot be reused; request a new code in Inspector.

## A Number doesn't connect

- If Inspector shows **This session stopped**, read the cause listed under the
  title. When no cause is listed, Inspector has no specific cause yet. Select
  **Retry**: it keeps the retained native device and reconnects the same
  Number; it does not open WhatsApp's pairing screen or create another device.
  While it reconnects, the dot on its tab shows the status; hover over or
  focus the tab to read it. If it stops again, Inspector shows **Retry did
  not work**.
- If the Number was never paired on this computer and nobody owns it, **Retry**
  or **Open** starts its pairing again. The stopped screen says so and Retry
  shows **Starting pairing** until WhatsApp's pairing screen opens. This also
  applies after you close its tab or sign out before pairing finishes.
- If your account still owns a Number this computer paired before, **Retry**
  reconnects that device.
- If the Number was paired here before but is no longer linked to your
  account, another account now uses it, or it is no longer available to you,
  the screen says why and offers **Check again** instead of Retry. If your
  Inspector access changed, it offers **Refresh access**. Inspector does not
  start a new pairing for a device it already linked.
- **This session is paused** means Inspector stopped the session, for example
  after another account took the Number. Select **Resume** to reconnect the
  linked device when the Number is available to you again.
- A tab labeled **Unconfirmed** has not been checked against your account yet,
  so Inspector doesn't yet know whether it is a test or Production Number. Inspector confirms it when the
  Number list loads or the tab reconnects.
- If Inspector can't reach Polymorfa, you stay signed in and your open
  Numbers keep running. The title bar shows **Can't reach Polymorfa.
  Retrying…** and **Retry now**; in a narrow window it shows only an icon
  and **Retry now**. The Number list keeps its last loaded
  state with **Last updated**. Inspector retries on its own. If Inspector
  starts while Polymorfa is unreachable, your open tabs show **Waiting for
  Polymorfa**; each one starts on its own when Polymorfa answers, if its
  Number is still linked to this computer. Otherwise the tab shows **This
  session is paused** with the reason, as described above. If it can't start
  yet, it shows **This session stopped** with **Retry**, and Inspector tries
  again on its own. Opening a new
  Number fails until Polymorfa is reachable; select **Retry** then.
  Inspector signs you out only when your sign-in is rejected or you choose
  **Sign out**.
- If the cause is **Access changed**, choose **Sign in again** or **Refresh
  access**. Retrying can't restore access that was removed.
- **Close tab** closes the tab and keeps the linked device.
- Confirm the number still belongs to the active project and your Polymorfa
  account owns it through Inspector.
- Check that `api.polymorfa.com`, `polymorfa.com` and the test number endpoint
  shown by the app are reachable over HTTPS and WSS.
- On the Console's **Numbers** page, confirm the Number and its owner before
  reinstalling. Test numbers are under **Test numbers**.

If a test number repeatedly returns to **Connecting** after its first open,
retry once. If the cycle continues, contact support with the Inspector version
and the failing step. Keep the number and its retained device while diagnosing
the failure; removing the number permanently clears its simulated state.

## A sent message is missing from Inspector

Select the sending number and open the recipient's chat. If the recipient
received the message but it is absent from the sending number's chat, contact
support with your Inspector version and the message ID returned by the send.
Do not send it again solely to refresh the chat: the recipient already received
it. Keep the number and its retained device while support investigates.

## Group messages fail to appear

If your message appears in your group chat but another participant sees a
decryption placeholder, keep the group and its linked devices while diagnosing
the failure. Contact support with your Inspector version, the message ID and
which participant view failed. Do not remove and recreate the group or resend
messages solely to refresh the other view.

## Retained history is unavailable

A real Number stays live when retained history is temporarily unavailable.
Continue with live messages or reopen the Number later. If Inspector says
retained history is off, enable Hosted Message Storage for that
Number before expecting earlier chats, contacts or messages. Test numbers have
no retained history.

## Inspect logs

Open **View → Toggle DevTools (Active Session)**, then select **Console**.
Inspector records initialization stages and WhatsApp runtime messages in
that console, including warnings and patch setup failures. The same command
closes DevTools when you finish.

Before sharing console output with support, remove message content, phone
numbers, device codes, and credentials.

## Get help

### Diagnostic reporting preferences

If your installed release includes **Share diagnostic error reports**, review
[what the preference sends](https://docs.polymorfa.com/testing/inspector/install#diagnostic-error-reports)
before enabling it. It is separate from permission to open a real Number.
Reports do not replace a support request or attach screenshots and console logs.

If a preference change fails to save, check that Inspector can write its local
settings and try again. Turning reporting off stops it for the running app even
if saving fails; confirm that the preference is off after restarting Inspector.

### Contact support

Email **support@polymorfa.com** with the Inspector version, operating system, the failing step, and redacted screenshots or logs. Never include team keys, project tokens, client tokens, QuickLink URLs, or device codes.

## See also

- [Install Inspector](https://docs.polymorfa.com/testing/inspector/install)
- [Open a Number in Inspector](https://docs.polymorfa.com/testing/inspector/devices)
- [Testing](https://docs.polymorfa.com/testing)
