Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Troubleshooting

Messages appear in one of three places: the status bar under the tabs, the Users panel, or in red as Error: … under a tab’s button. Error text from Google is passed through unchanged, so search the message itself if it is not listed here.

The app does not open

If no graphics backend works, the app shows a dialog that begins “Firebase Token Toolkit could not start.” The app tries OpenGL first and then wgpu, which can fall back to a software renderer, so this almost always means a virtual machine or remote desktop session with no usable graphics at all. Enabling 3D acceleration for the VM usually fixes it.

On Linux, launching from a terminal shows the detail. A line like OpenGL backend unavailable (…); retrying with wgpu is informational; the app carries on with wgpu.

Service account

MessageCause and fix
Could not load service account: read service account file: <path>The file cannot be read. Check that it exists and that your user can read it.
Could not load service account: parse service account JSON: <path>The file is not valid JSON, or not a service-account key. Download a fresh key.
Could not load service account: service account JSON must contain client_email and private_keyThe JSON is some other kind of credential, such as a web app config. Use Generate new private key in the Firebase console.
parse RSA private key (must be PEM PKCS#8 / PKCS#1)The private_key field has been edited or mangled. Download a fresh key.
The file picker closed unexpectedlyOn Linux, the XDG desktop portal is missing or crashed. Install xdg-desktop-portal-gtk or your desktop’s portal.
● not configured after a restartThe saved key file has moved. Use Browse… to find it again.

Authentication with Google

MessageCause and fix
oauth2 token error (400): … invalid_grant …The key has been deleted or disabled in Google Cloud, or your system clock is off by several minutes. Check the clock, then generate a new key.
oauth2 token error (401): …The service account no longer exists. Generate a key for an active account.
POST oauth2 token (no further detail)The request never reached Google. Check your network connection and any proxy.

Users panel

MessageCause and fix
Load a service account and set Project ID to browse users.Load a key and make sure Project ID is filled in.
No user found for that queryLookup needs the whole value: a complete email (case does not matter), a phone number in full + country-code form, or an exact UID. To match part of a value, type into the search box without pressing Enter; that filters the users already loaded.
API error (403): …The service account lacks permission to read users, or the Identity Toolkit API is disabled for the project.
GET accounts:batchGetThe request never reached Google. Check your connection.

Tokens

MessageCause and fix
API key requiredThe selected app has no API key. Click Load apps, or paste the key.
API error (400): INVALID_CUSTOM_TOKEN : Invalid assertion format. 3 dot separated segments required.The pasted text is not a whole token. It usually lost characters while being copied.
API error (400): INVALID_CUSTOM_TOKEN … with other textThe token has expired (custom tokens last one hour) or is malformed. Generate a new one.
API error (400): CREDENTIAL_MISMATCHThe custom token was signed with a key from a different project than the API key belongs to. Check that the profile’s key and API key are from the same project.
API error (400): API key not valid. Please pass a valid API key.The API key is wrong or deleted. Copy it again from Project settings → General.
API error (403): Requests from this Android client application <empty> are blocked. (or the iOS equivalent)The key is restricted to an Android or iOS app, but the selected app is a different type, or its Package or Bundle ID is empty. Select the matching app, or fill in its identifiers.
API error (403): Requests from this Android client application dev.example.app are blocked.The package or SHA-1 does not match the key’s restriction. Check both against the key in Google Cloud Console → Credentials. A SHA-1 marked invalid in the top bar is not sent.
API error (403): Requests from this iOS client application <bundle> are blocked.The bundle ID does not match the key’s restriction.
API error (403): … are blocked. (other)The API key has restrictions that exclude the Identity Toolkit API or the App Check API. Loosen them in Google Cloud Console.
Invalid claims JSON: … / custom claims must be a JSON objectThe optional claims box must hold a JSON object, such as {"role":"admin"}, or be empty.
Paste a custom token firstThe Custom -> ID Token input is empty.

User Custom Claims

MessageCause and fix
Serialized claims are N bytes; Firebase limit is 1000 bytes.Firebase rejects claims over 1,000 bytes. Shorten keys or move data to your database.
Claims editor is empty (use 'Clear all claims' to wipe).Save with an empty editor is refused on purpose. To remove every claim, use Clear all claims.
Claims must be a JSON object.Top-level arrays, strings and numbers are not allowed.
User not foundThe user was deleted after you picked them. Refresh the Users panel.

App Check

MessageCause and fix
Debug token requiredPaste the debug token into the tab.
API error (403): App attestation failed.The debug token is not registered for this App ID. Check it under App Check → Manage debug tokens, and that it was registered for the same app as the App ID in the top bar.
API error (403): … with other textThe App Check API is not enabled for the project, or the API key’s restrictions exclude it.
API error (404): …The App ID does not exist in the project named in Project ID.

Load apps

MessageCause and fix
Loading apps failed: API error (403): …The service account may not read Firebase apps, or the Firebase Management API is disabled. Grant Firebase Viewer (roles/firebase.viewer), or add the app by hand with + Add app.
No apps found in this Firebase project.The project has no registered apps. Add one under Project settings → General → Your apps.
Loaded apps: … Some details are missing — …The list loaded, but one app’s config or certificates could not be read. That app is listed without its key; fill it in by hand.

Linux desktop issues

Browse… does nothing. The file chooser goes through an XDG desktop portal. Install xdg-desktop-portal-gtk (or your desktop’s portal) and log in again.

Copy shows copy failed: …. The clipboard needs X11 or XWayland. Under a pure Wayland session without XWayland, select the token text and copy it with Ctrl+C instead.

The Changelog and Security notes links in the About dialog point at the git tag matching the app’s version. A build from an untagged commit has no such tag, so the links 404. Release builds are not affected.