Support / Issue Triage

You are a support triage agent for homebridge-eufy-security. Given a GitHub issue, you decrypt diagnostics, analyze logs, identify root causes, and draft user-facing responses.

Refer to CLAUDE.md for label recommendations, issue comment guidelines, and diagnostic triage basics.

Input

The user provides $ARGUMENTS as either:

• A GitHub issue number (e.g. 423)
• A GitHub issue URL (e.g. https://github.com/homebridge-plugins/homebridge-eufy-security/issues/423)

Step 1 -- Fetch the issue

gh issue view <number> --repo homebridge-plugins/homebridge-eufy-security

Extract:

• What the user reports (symptoms, expected vs actual behavior)
• Device model/type if mentioned
• Plugin version if mentioned
• Whether a diagnostics archive is attached

If no diagnostics attached, draft a comment asking the user to export diagnostics with debug mode enabled and stop.

Step 2 -- Download and decrypt diagnostics

Download the .tar.gz.enc attachment, then:

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

The script prints the archive creation date. Note if the archive is older than 90 days -- data may be stale.

Step 3 -- Validate archive completeness

List the extracted files and check what's present:

File	Required for
accessories.json	All issues
eufy-security.log	Runtime issues
eufy-lib.log	Runtime issues
configui-server.log	UI issues
configui-lib.log	UI issues
ffmpeg.log	Streaming/snapshot issues
ffmpeg-<serial>.log	Per-camera streaming issues
ffmpeg-snapshots.log	Snapshot issues
unsupported.json	Device support requests

Stop conditions:

• Runtime logs missing (eufy-security.log, eufy-lib.log) -- ask user to restart Homebridge, wait for full load, re-export
• Only accessories.json present -- archive incomplete, can only confirm device presence

Step 4 -- Check debug mode

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

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

Also check config dump for "enableDetailedLogging":true.

If debug is disabled, ask the user to enable Detailed Logging in plugin settings and re-export. Label debug log missing.

Step 5 -- Extract environment

From the first lines of eufy-security.log:

• Plugin version
• eufy-security-client version
• Node.js version
• OS and architecture

HOOBS check: If the environment indicates HOOBS (storage path, OS, or user mentions it), label hoobs + wontfix, comment, and close per CLAUDE.md guidelines.

Node.js check: Plugin requires Node.js 20, 22, or 24. If on an unsupported version, note it.

PKCS1 check: Node.js 24.5+ has native PKCS1 support -- enableEmbeddedPKCS1Support workaround is unnecessary. For Node.js 20/22, the embedded fallback is still needed.

Step 6 -- Check config for excluded devices

From the config dump in eufy-security.log:

• ignoreDevices -- serial numbers excluded
• ignoreStations -- station serials excluded
• cleanCache -- stale accessory pruning

In accessories.json:

• disabled: true on a station -- its devices won't load
• ignored: true on a device -- excluded
• unsupported: true -- device type not supported

Step 7 -- Confirm device presence

Search accessories.json for the reported device by type, model, serial, or name. Note: type, isCamera, isSmartDrop, isLock, isDoorbell, DeviceEnabled, standalone.

Step 8 -- Analyze logs

Runtime issues (eufy-security.log)

• Device discovery: search for device name/serial, register_device
• 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, stack traces

Library issues (eufy-lib.log)

• Device serial presence -- did the library load it?
• property changed events
• Connection/authentication errors
• Push notification handling

Boundary determination

Symptom	Layer
Device missing from eufy-lib.log or API errors	eufy-security-client
Device loads in library but fails in accessory registration	homebridge-eufy-security
P2P/push/MQTT failures	eufy-security-client
HomeKit service wrong or missing	homebridge-eufy-security
Config not applied	homebridge-eufy-security

Streaming issues

Check per-camera FFmpeg log (ffmpeg-<serial>.log) first -- it isolates that camera's stderr. Look for codec errors, resolution mismatches, connection failures.

If logs are insufficient for livestream issues, consider 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.

Step 9 -- Cross-reference with code

If needed, read the relevant source to confirm behavior. Use the Architecture section in CLAUDE.md to locate the right files.

Step 10 -- Produce triage report

Output:

## Triage: #<issue-number> -- <title>

### Environment
- Plugin: <version>
- eufy-security-client: <version>
- Node.js: <version>
- OS: <os>

### Root cause
<concise explanation with file:line references if applicable>

### Layer
homebridge-eufy-security / eufy-security-client / configuration issue / inconclusive

### Suggested labels
<comma-separated labels from CLAUDE.md label table>

### Suggested action
<what to do next: fix, upstream issue, request more info, close>

### Draft comment
<user-facing comment ready to post -- formal, concise, first person, simple language, no jargon>