Skip to content
Shortcut: /, ⌘K or Ctrl+K

Troubleshoot Inspector

Fix Inspector download, authorization and connection problems.

View as Markdown

Find the symptom below and follow its steps. If the problem continues, contact support.

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. 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.
  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.
  • 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 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#