Common Errors

Here are some of the common problems you may experience with the plugin and how to resolve them.

Sign-In / Login Errors

Shark IQ uses SharkNinja's hosted sign-in rather than a plain username and password:

• In the plugin's Settings tab, use the OAuth Assistant: click Generate Login URL, open the URL and sign in. Paste the callback URL (or just the code) into Callback URL or OAuth Code, click Exchange Code, then restart Homebridge.
• If you are in Europe or the UK, turn on SharkClean European Server and save before generating the URL - the US and EU accounts use different servers.
• If sign-in used to work and now fails with an "unauthorized" error, your saved token has likely been revoked (for example by signing out in the SharkClean app). Generate a fresh login code and paste it in again.
• If it still fails, remove the cached auth files (.sharkiq_oauth.json, .sharkiq.json and .sharkiq_auth0.json) from your Homebridge storage directory and sign in again from scratch.

"Unable to get token data. HTTP 403"

This nearly always means the login code was already used or has expired, rather than anything being wrong with your account. The code is single-use and only lasts a few minutes.

The usual causes:

• The SharkClean app opened when you clicked Accept. The app treats the final address as an Alexa-style account link, shows a "Linking Error", and spends the code in the process. Use a browser on a computer that does not have the app installed.
• Too long passed between signing in and clicking Exchange Code.
• The login URL and the code did not match. Generating a new URL invalidates any older login tab, so do not mix them.

In every case the fix is the same: click Generate Login URL again, sign in with the new URL, and exchange the code straight away.

The browser will not show the callback address

Safari in particular discards the address instead of displaying it. See Installation for a method that works in every browser, using the browser's Network tab.

Vacuums Not Appearing

• The easiest option is to leave the vacuums list empty - the plugin then adds every robot on your account.
• If you do list specific robots, use the DSN identifier the plugin logs on startup ("Found N vacuum(s)..."), not the serial number printed in the SharkClean app. Matching ignores case and any spaces at the start or end.
• Make sure the robot is set up and visible in the SharkClean app first - the plugin can only see what the account sees.

Vacuum Ignores Start or Stop Commands

Newer vacuums only act on commands sent through SharkNinja's newer API. If the plugin could not connect to it, the log shows:

Could not connect to the new SharkNinja API - commands will use the Ayla API.

• Sign in again through the OAuth Assistant in the plugin's Settings tab, then restart Homebridge.

Robot Not Registering Over Matter

• Matter is used automatically on Homebridge v2.0+ with Matter enabled, and the plugin falls back to HAP when Matter is unavailable.
• A robot that does not appear over Matter is often a knock-on of the DSN not matching - fix the vacuums list (or leave it empty) first.

Getting More Help

• Search the existing issues - someone may have had the same problem.
• If not, please open a support request and include your Homebridge log. For more detail in the log, turn on Homebridge Debug Mode (Homebridge UI → Settings → Startup & Environment; a child bridge has its own Debug Mode in its child bridge settings), then restart.