Common Issues - homebridge-plugins/homebridge-eufy-security GitHub Wiki

Common Issues

Check if your issue is listed below. If not, see Troubleshooting for diagnostic steps.

Login and Authentication

CAPTCHA or 2FA — ERROR Not connected can't continue!

If you see one of these messages:

Important Notice: CAPTCHA Required
Your account seems to have triggered a security measure...

Attention: Two-Factor Authentication (2FA) Requested
It appears that your account is currently under a temporary 24-hour flag...

Fix:

  1. Disable the Eufy Security plugin
  2. Restart Homebridge
  3. Go to the plugin settings and click the refresh button
  4. Complete the CAPTCHA and/or 2FA prompt
  5. Devices should reappear — click Save
  6. Re-enable the plugin
  7. Restart Homebridge

Prevention: Use a dedicated admin account to avoid conflicts with the Eufy app.

No station with serial number

No station with serial number: TXXXXXXXXXX!

This error means you're using a guest account instead of an admin account. Fix by granting admin rights through the Eufy app. See dedicated admin account setup.

Streaming Issues

For streaming feature documentation (presets, advanced config), see Streaming.

Streaming Troubleshooting Checklist

Try these steps one at a time. Restart Homebridge after each change and test streaming.

  1. Enable debug logging and check for error messages
  2. If FFmpeg crashes, also enable ffmpeg debug in the device's Advanced Video Config
  3. If your camera connects through a Homebase: restart it (unplug and reconnect). A red LED indicates a network issue.
  4. Ensure no other camera on the same Homebase is streaming simultaneously (including snapshot requests)
  5. Check stream quality settings in the Eufy app — try lowering codec and quality temporarily
  6. Disable features that add FFmpeg load:
    • Disable Talkback
    • Disable Audio
    • Disable HomeKit Secure Video
    • Set snapshot handling to 'Cloud Snapshots'
  7. Try RTSP vs Local Livestream (if your device supports both)
  8. Try different presets: No preset, Copy, and Performance
  9. Try running Homebridge on more powerful hardware

If one step fixes it, re-enable features one by one to isolate the cause.

Livestreams abort after ~30 seconds

The CameraMaxLivestreamDuration setting in Plugin Settings controls how long a livestream stays alive. Increase this value. See Configuration.

"Local livestream didn't start in time"

This means the P2P stream handshake failed. Common causes and fixes:

  • Eufy app settings: Set codec and quality to low, then test. Less data = easier to process.
  • Slow hardware: Use the 'Performance' preset to reduce encoding workload.
  • Homebase issues: Restart your Homebase. A red LED usually indicates a network problem.
  • IP blocked by Eufy: In rare cases, restarting the plugin too many times can trigger a server-side block. Reset your internet connection to get a new public IP, or try a different Eufy account.

Streams take a long time to start

Causes range from slow hardware to snapshot handling stalling the request queue. Homebridge processes requests sequentially, so:

  • A slow snapshot request blocks subsequent stream requests
  • Set snapshot handling to 'Cloud Snapshots' for the fastest response
  • Try unbridging the device to decouple it from other accessories

Streams work on one device but not another

HomeKit controllers (iPhone, Apple TV, HomePod) each request different stream parameters. If the stream doesn't match what the controller expects, it may cancel it. Try adjusting the Advanced Video Config.

Talkback aborts after 20-30 seconds

Usually caused by a firewall blocking the FFmpeg talkback process. Add a firewall rule to allow the FFmpeg executable. Windows may not show a popup when blocking network activity.

The FFmpeg path can be found in debug logs:

DEBUG: [Doorbell] [Video Process] Stream command: /usr/local/lib/node_modules/.../ffmpeg [...]

FFmpeg not found

The plugin ships FFmpeg via ffmpeg-for-homebridge. If it isn't detected, install it globally:

sudo npm install -g ffmpeg-for-homebridge

Hyper-V networking issue

Hyper-V virtual network drivers can cause P2P streams to fail. See:

Apple Watch streaming only works on WiFi

This is a known Apple HomeKit bug that also affects native HomeKit cameras. Streaming fails when the watch is connected through a paired iPhone instead of its own WiFi or cellular connection.

HomeKit Issues

Unexpected behaviour after changing settings

HomeKit sometimes has trouble with accessories that update their capabilities after being added. When changing device settings (like enabling camera mode), you may need to:

  1. Remove the device from HomeKit
  2. Remove it from the Homebridge cache (see below)
  3. Re-add the device

We recommend using a child bridge and unbridging individual devices where possible. See Bridged and Unbridged Mode.

Unable to add device after switching bridged/unbridged mode

When a device was previously bridged and you switch to unbridged mode, HomeKit may fail to find it. Fix:

  1. Open Homebridge UI → three-dot menu → Homebridge Settings
  2. Scroll to Reset → click Unpair Bridges / Cameras / TVs / External Accessories
  3. Find the problematic device and remove it
  4. Add the device again in HomeKit

For more details, see Bridged and Unbridged Mode.

Device Updates and Events

Devices get no updates (motion events, sensor status)

You must enable push notifications for each device in the Eufy app. The plugin relies on push notifications through the Eufy cloud to receive real-time events.

For motion detection, ensure the security mode (Home/Away/Night/Custom) is configured to send push notifications:

Snapshot image is old

Battery cameras limit polling to preserve battery life. You may not always get the latest snapshot. The plugin has configuration settings to control snapshot behaviour — see device settings in the Homebridge UI.

Update Issues

Problems after updating

If the plugin misbehaves after an update (especially beta versions), cached data from previous versions may be interfering. Clear the plugin storage:

See Reset / Clear

Unexpected UI error after upgrade

Try opening the Homebridge UI in an incognito/private browser window. If this fixes it, clear your browser cache.

Node.js Compatibility

Certain Node.js versions break livestream/P2P streaming due to a removed cryptographic protocol. See the dedicated Node.js Compatibility page for the full compatibility matrix and solutions.

Quick fix: Use Node.js 20.11.0 (stable) or >= 24.5.0 (latest features).

Platform-Specific

HOOBS

HOOBS is not supported. We do not provide assistance for HOOBS setups.

Still Need Help?

If your issue isn't listed here:

  1. Follow the Troubleshooting steps to collect diagnostics
  2. Search existing issues
  3. File a new issue with your diagnostics archive
  4. Join us on Discord