Prompt file imported from homebridge-plugins/homebridge-eufy (.github/prompts/diag-triage.prompt.md). Copyright stays with the author.

Diagnostic Prompt — Issue Triage

Context

This prompt is used to triage issues reported by users of the homebridge-eufy-security plugin. Diagnostics are collected via the plugin UI and contain log files and a device snapshot.

Important: This plugin (homebridge-eufy-security) relies heavily on the underlying eufy-security-client library (by bropat). During triage, narrow down ASAP whether the issue originates in homebridge-eufy-security (accessory registration, HomeKit mapping, service pruning, config handling) or in eufy-security-client (device discovery, property events, push notifications, P2P connections, API communication).

Diagnostics Archive Structure

Diagnostics archives are encrypted (RSA-4096 + AES-256-GCM) and include a creation timestamp in the header. The downloaded file has a .tar.gz extension (the content is encrypted despite the extension — this allows direct upload to GitHub). Before analysis, decrypt it:

node scripts/decrypt-diagnostics.mjs <file>.tar.gz

The script prints the archive creation date and warns if the archive is older than 90 days.

A complete diagnostics folder contains:

diagnostics-YYYY-MM-DD-HH-MM-SS/
  accessories.json              — device tree snapshot generated by the UI
  unsupported.json              — unsupported device intel (if any)
  configui-server.log           — plugin UI server log
  configui-lib.log              — eufy-security-client library log used by the UI
  eufy-security.log             — plugin runtime log
  eufy-lib.log                  — eufy-security-client library log
  ffmpeg.log                    — global FFmpeg transcoding log (optional)
  ffmpeg-<serial>.log           — per-camera FFmpeg log (one per camera that has streamed)
  ffmpeg-snapshots.log          — snapshot FFmpeg log (optional)
  *.log.gz                      — rotated compressed log archives

There are two categories of logs depending on the area of the issue:

Plugin WebUI (UI-related issues)

• accessories.json, configui-server.log, configui-lib.log

Plugin Runtime (Homebridge runtime issues)

• accessories.json, eufy-security.log, eufy-lib.log

Optional

• ffmpeg.log — global FFmpeg log, relevant for streaming/snapshot issues
• ffmpeg-<serial>.log — per-camera FFmpeg logs, isolate streaming/recording issues to a specific camera
• ffmpeg-snapshots.log — snapshot-specific FFmpeg output
• unsupported.json — raw device properties for unsupported devices (useful for device-support requests)

Safeguard — Incomplete Diagnostics

Before any analysis, check which files are present:

• If runtime logs (eufy-security.log, eufy-lib.log) are missing: the plugin was not running when diagnostics were exported. Stop analysis — ask the user to upgrade to the latest beta (Beta Versions) and follow the Basic Troubleshooting steps to restart Homebridge, reproduce the issue, and re-export diagnostics.
• If UI logs (configui-server.log, configui-lib.log) are missing: the UI server wasn't active. These are only needed for UI-related issues.
• If only accessories.json is present: the archive is incomplete. Only device presence can be confirmed, not runtime behavior. Same guidance as above — ask the user to upgrade to the latest beta and follow the Basic Troubleshooting steps.

Do not attempt further analysis without the relevant logs for the reported issue area.

Diagnostic Steps

1. Validate archive completeness (see safeguard above)

2. Check if debug mode is enabled

In eufy-security.log, check the first few lines for indicators:

• Debug enabled: log level shows DEBUG, template includes file/line references (e.g. platform.ts:311), logger name contains the version (e.g. [EufySecurity-4.4.2-beta.41])
• Debug disabled: log level starts at INFO, no file/line references, logger name is just [EufySecurity]

You can also confirm from the config dump in the log: "enableDetailedLogging":true or false.

If debug is disabled, the logs will lack critical details (no DEBUG entries for device discovery, characteristic registration, property changes). Ask the user to upgrade to the latest beta (Beta Versions) and follow the Basic Troubleshooting steps to enable Detailed Logging, reproduce the issue, and export diagnostics.

3. Extract environment info

From the first lines of eufy-security.log, extract:

• Plugin version (e.g. 4.4.2-beta.41)
• eufy-security-client library version
• Node.js version
• OS and architecture
• Storage path

Node.js version check

Starting with version 4.4.2, the plugin is compatible with Node.js 20, 22, and 24.

This version works with the latest bropat eufy-security-client library, which includes significant fixes for Homebase communication.

PKCS1 / Node.js 24.5+

Node.js 24.5+ re-added native PKCS1 padding support. If the user is on Node.js 24.5+, the enableEmbeddedPKCS1Support workaround is no longer needed — advise them to disable it ("enableEmbeddedPKCS1Support": false or remove it from the plugin UI config) when testing. For users on Node.js 20 or 22, the embedded PKCS1 fallback remains necessary.

If the environment indicates HOOBS (storage path, OS details, or user mentions it): label hoobs + wontfix and close the issue. The Plugin UI is known to not work properly on HOOBS and we do not support it. Comment on the issue:

Thank you @<username> for reporting this.

Unfortunately, HOOBS is not supported. The Plugin UI is known to not work properly on HOOBS and we are unable to provide support for it.

I recommend migrating to Homebridge for the best experience with this plugin.

4. Check config for excluded devices

From the config dump in eufy-security.log, check:

• ignoreDevices — array of serials explicitly excluded
• ignoreStations — array of station serials excluded
• cleanCache — if true, stale accessories are pruned on restart

Also in accessories.json, check:

• disabled: true on a station — prevents its devices from loading
• ignored: true on a device — device is excluded
• unsupported: true — device type not supported by the plugin

5. Confirm device presence

In accessories.json, search for the reported device by type, model, serial, or name. Note key properties: type, isCamera, isSmartDrop, isLock, isDoorbell, DeviceEnabled, disabled, ignored, unsupported, standalone.

6. Analyze logs based on issue area

For runtime issues — check eufy-security.log:

• Device discovery: search for device name/serial, register_device, isSmartDrop, isCamera, isLock, etc.
• Discovery warnings: [DISCOVERY WARNING], [DEVICE SKIP], [STATION SKIP]
• Accessory instantiation: Constructed, REGISTER CHARACTERISTIC, SEED
• Service pruning: Pruning unused service
• Property events: Property Changes, ON '...
• Errors: Error, error, stack traces

For runtime issues — check eufy-lib.log:

• Device serial presence — confirm the library loaded it
• property changed events for the relevant properties
• Connection/authentication errors
• Push notification handling

Scope determination: If the device doesn't appear in eufy-lib.log or fails at the library level (API errors, P2P failures, missing property events), the issue is likely in eufy-security-client. If the device loads in the library but fails during accessory registration, HomeKit mapping, or service pruning, the issue is in homebridge-eufy-security.

For livestream / streaming / snapshot issues

Check the per-camera FFmpeg log (ffmpeg-<serial>.log) for the affected camera. This isolates FFmpeg stderr output for that specific device, making it much easier to spot codec errors, resolution mismatches, or connection failures versus the global ffmpeg.log which mixes all cameras.

Also check ffmpeg-snapshots.log for snapshot-related issues.

Livestream problems (video feed, P2P, RTSP) are often device-specific and hard to reproduce without access to the actual hardware. When logs alone aren't sufficient to diagnose the issue, offer to test against the user's device by requesting temporary device sharing:

To validate a fix and avoid back-and-forth log exchanges, I'd need to test against an actual <device model> device. Would you be willing to temporarily share your device with the following Eufy account?

homebridge.eufy.sec@gmail.com

Please also let me know which country your account is registered in.

This is entirely optional — no obligation. I understand sharing device access requires trust. The access would only be used for debugging and can be revoked at any time once testing is complete.

For UI issues — check configui-server.log and configui-lib.log:

• Login/authentication flow
• Device listing errors
• API request/response issues

7. Cross-reference with code

Key source files:

• src/platform.ts (register_device) — device registration logic, note that devices can stack multiple capabilities (independent if blocks, not else if)
• src/accessories/BaseAccessory.ts — characteristic registration, service pruning
• src/accessories/Device.ts — sensor/battery service, property helpers
• src/accessories/<Type>Accessory.ts — device-specific HomeKit mapping
• homebridge-ui/server.js — UI server logic, diagnostics generation

Issue Type

GitHub issue types classify the issue at creation. Issue templates auto-assign these:

Issue types replace the old bug and enhancement labels — do not add those labels manually.

Label Recommendations

Based on triage findings, suggest one or more labels for the issue:

Closing Comments

When a fix has been merged and published, leave a concise comment on the issue:

• Audience is end users — keep language simple, avoid internal jargon or FFmpeg/P2P technical details
• Don't scope the fix to a specific device model when it applies broadly (e.g. "all cameras using P2P" not just "the E42")
• Always check the published beta version (npm view @homebridge-plugins/homebridge-eufy-security dist-tags) and mention it so the user knows which version to install
• Label the issue resolved in beta