Troubleshooting

[Overview](../) · Help & Security

Use this guide to diagnose installation issues, unavailable profiles, live-update failures and rate limits. Start with the visible symptom, then follow the checks in order.

The package will not install

1. Check the spelling: @iconical/presence.

2. Check whether the intended version has actually been published to npm. An unavailable package is different from a runtime error.

3. Use Node.js 18+ or Bun, and ensure a supported package manager is installed.

4. If testing an unpublished archive, build it and install the .tgz from the Installation guide.

If TypeScript cannot find an import, make sure you use one of the documented subpaths (/react, /vue, /svelte, /react-ui) and that the corresponding framework dependency is installed.

A user's presence is unavailable (404)

• Confirm the person joined the official PresenceKit server.
• Ask them to run /confirm and approve sharing.
• Check that the application uses their numeric Discord user ID, not a username.
• Have the user run /status if they want to verify their consent state.

The API deliberately does not distinguish an unknown account from a user who has not approved sharing. Do not interpret 404 as offline.

The response says pending

The user is approved, but there is currently no fresh Discord presence snapshot. Display “Waiting for a Discord update”, not “Offline.” Check again later through subscribePresence() or the framework adapter.

REST works but live updates stop

For a verified, consenting user, inspect the browser Network panel for an SSE request like:

Check that the response is text/event-stream and that a proxy, browser extension, or intermediary is not blocking/buffering the connection. In auto mode, PresenceKit switches to REST polling after repeated stream problems and later attempts SSE again.

For diagnosis, you can force polling:

transport: "sse" intentionally does not fall back to REST. It also requires EventSource in the runtime.

HTTP 429 / 503

Avoid tight retry loops. Frequent polling does not improve the availability of data that Discord has not delivered.

A game image is blank

Not every game has published artwork. Use getActivityArtwork() for safe image selection, or ActivityCard for a monogram fallback. Third-party image hosts can also fail or block requests. See Activity artwork.

Other common questions

Does the app need a Discord token? No. Consumer code uses the official PresenceKit API without Discord bot credentials.

Can the API URL be changed? No. The official package uses a fixed endpoint and has no baseUrl configuration.

Why is a team member missing? Each user must independently approve /confirm; a batch omits users who are no longer eligible.

See API reference and Privacy for details.