Troubleshooting

Troubleshooting

Authentication failed / 2FA not working

• Open Plugin Settings in the Homebridge UI and use the Start Login button — this is the recommended way to authenticate, especially for 2FA accounts.
• Confirm your username and password work in the Hubspace app on your phone.
• If login previously worked but stopped, delete hubspace-tokens.json from your Homebridge storage directory and log in again via Plugin Settings.
• If the 2FA code expires before you enter it, the session times out after 10 minutes — start the login flow again from Plugin Settings.
• Check your spam folder if the 2FA email doesn't arrive within a minute.

Accessories show as No Response

• Check Homebridge logs for [Hubspace] error lines.
• Enable "debug": true in your plugin config temporarily to see API call activity (GET STATE, SET STATE, token refresh).
• Verify your Homebridge host can reach semantics2.afero.net and api2.afero.net.
• If the issue is intermittent, the device may be going offline in the Hubspace cloud — check the Hubspace app to confirm the device is online there.

Device not appearing in HomeKit

• The log will show an Unsupported deviceClass warning for any skipped device.
• Enable "debug": true for a full capability dump in the log.
• Alternatively, run the standalone dump script — no Homebridge restart needed.

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/ctrlcmdshft/homebridge-hubspace-platform/main/scripts/dump-devices.js -o /tmp/hubspace-dump.js && node /tmp/hubspace-dump.js

Windows (PowerShell — Windows 10 1803+ / Windows 11):

curl.exe -o $env:TEMP\hubspace-dump.js https://raw.githubusercontent.com/ctrlcmdshft/homebridge-hubspace-platform/main/scripts/dump-devices.js; node $env:TEMP\hubspace-dump.js

Windows (PowerShell fallback — any version):

Invoke-WebRequest -Uri https://raw.githubusercontent.com/ctrlcmdshft/homebridge-hubspace-platform/main/scripts/dump-devices.js -OutFile $env:TEMP\hubspace-dump.js; node $env:TEMP\hubspace-dump.js

• If the device class is unsupported, open a GitHub issue with the dump output.

Device appears but a characteristic is wrong

• Enable "verbose": true and restart Homebridge.
• Every poll cycle will print a State for "..." line with every capability and value the API returned.
• Paste that line in a GitHub issue along with a description of what HomeKit shows vs. what you expect.

State changes are slow to reflect in HomeKit

• By default the plugin uses real-time push (Conclave) for ~500 ms updates — check that disableConclave is not set to true in your config.
• If Conclave is enabled but updates are still slow, check Homebridge logs for Conclave connection errors.
• Polling runs every 30 seconds as a fallback — you can lower pollingInterval if needed (minimum 10 s).

Fan or light shows a fault indicator

• If exposeStatusFault is enabled, a fault indicator appears when the device is reported offline by the Hubspace cloud.
• Check the Hubspace app — if the device shows as offline there too, it's a hardware/network issue, not a plugin issue.