Troubleshooting Device Connections

Troubleshooting Device Connections

If you're having trouble with devices not connecting or responding, try these solutions.

Plugin Connection Issues

If you're using the Staykey plugin (recommended):

• Check connection status: In Home Assistant, go to Settings → Devices & Services and find Staykey. It should show "Connected."
• Verify internet access: The plugin needs outbound internet access to reach Staykey's cloud. Check that your Home Assistant can reach the internet.
• Check the gateway token: Go to Staykey under Properties → Integrations and verify your gateway token matches what's configured in Home Assistant.
• Restart the plugin: In Home Assistant, go to Settings → Devices & Services, find Staykey, click the three-dot menu, and select Reload.
• Check logs: Go to Settings → System → Logs and search for "Staykey" to see connection status and any errors.

Direct Connection Issues

If you're using the direct connection method (public URL + access token):

• URL accessibility: Verify your Home Assistant URL is reachable from outside your network (try opening it from your phone with WiFi off).
• Token validity: Check that your Long-Lived Access Token hasn't expired or been deleted. Generate a new one if needed.
• Nabu Casa / Tailscale: If using a remote access service, verify it's still running and configured correctly.

Device Not Appearing in Staykey

• Check Home Assistant: Verify the device is properly added and available in Home Assistant first.
• Run device discovery: In Staykey, go to your property's integration settings and re-run device discovery.
• Device type: Ensure the device type is supported (locks, thermostats, switches, covers).
• Plugin users: The plugin discovers devices with rich metadata (manufacturer, model, capabilities). If a device doesn't appear in discovery, it may not be fully initialized in Home Assistant — check that the device interview is complete in the Z-Wave JS integration.

Device Not Responding

• Power check: Ensure the device is powered on and has battery (for battery-powered devices).
• Range issues: Z-Wave devices need to be within range of the hub. Try moving the device closer.
• Network issues: Check your Home Assistant hub is online and accessible.
• Check Home Assistant: If you're using the Staykey plugin, check the device status in Home Assistant directly. The plugin captures health data — dashboard surfacing for health alerts is coming soon.
• Re-pair device: Try removing and re-adding the device in Home Assistant.

Access Codes Not Working

• Code verification: If you're using the Staykey plugin, it automatically verifies that codes were written to the lock. Check the activity log for verification status.
• Code limit: Some locks have a limit on the number of user codes. Check your lock's specifications.
• Code format: Ensure codes meet your lock's requirements (length, allowed characters).
• Sync delay: With the direct connection, codes may take a few minutes to sync to the lock. The plugin handles this faster with local execution and verification.

Entity Renamed or Removed

If you've renamed a device or entity in Home Assistant:

• Plugin users: The plugin detects entity renames automatically and updates Staykey. No action needed.
• Direct connection users: You may need to re-run device discovery in Staykey if a device stops responding after being renamed in Home Assistant.

Still Having Issues?

If none of these solutions work, please contact our support team with details about your device, connection method (plugin or direct), and the issue you're experiencing.