Layered Troubleshooting Method

Layered Troubleshooting Method

中文 · Logging System and Maintenance

Find the last layer proven successful, then inspect the next one. Do not infer every component from a final “black screen” or “disconnected” symptom, and do not use reconnection as the default fix for an unknown failure.

Order

Layer	Success evidence	Failure entry
1. Configuration/identity	Session, candidate, transport id, tunnel, and codec configuration are explicit	Session Configuration and Connection Lifecycle
2. ADB	Actual winner verifies and the same object is in the registry	ADB Connection Lifecycle
3. Server/tunnel	Old resources are gone; new SCID, forward/direct mode, and server startup align	Runtime Main Path
4. Sockets	Video → optional audio → control are present and dummy byte confirmed	Runtime Main Path
5. Metadata/codec	Header is exact, codec id/size valid, MIME pair compatible	Encoding and Decoding
6. Decoder/Surface/audio	Configure/start, output, Surface, and AudioTrack work	Encoding and Decoding; Interaction Performance
7. Control/UI	Sender/receiver active; pointer, clipboard, and menu routes work	Interaction Performance; Clipboard

Three runtime evidence layers

1. SessionState: the overall phase where the run stopped.
2. The last relevant SessionEvent: the structured fact or action request that occurred.
3. SessionComponentStateSnapshot: the component that failed to reach its expected state.

Only then use logcat, file logs, and event-monitor projections to reconstruct timing. Monitor state and log strings never override formal session facts.

Common tags

• ADBC: candidates, connection, verification, registry, and lanes.
• ADBP: Wireless Debugging pairing.
• USBC: USB scan, permission, and detach.
• SCLI / SSVR / SKPK: client orchestration, server shell, packet/metadata.
• SEVT: cross-module event projections.
• VDEC / ADEC: video/audio decoders.
• RDSP / CTRL / TOCH / FCTL: Surface, control, touch, floating menu.
• SSVC: foreground ADB protection.
• MGMT: management pages.

Correlate one attempt by session id, transport device id, SCID, local port, and socket type. If these identities disagree within a trace, investigate crossed resources or stale tasks first.

Scenario routing

• USB missing: interface scan → permission → refreshed authorized UsbDevice; after unplug, inspect detach matching and registry removal.
• Pairing succeeds but connection fails: inspect TLS connect service/port, trust material, and ADB verification instead of repeating pairing-code diagnosis.
• Management works but no remote image: ADB passed; continue with server, sockets, metadata, and decoder.
• Connected but black screen: inspect video metadata, decoder output, and Surface; socket connected is not media ready.
• Audio missing: separate configuration disabled, server codec id 0, header error, and decoder/AudioTrack failure.
• Control disconnects while idle: confirm control socket soTimeout=0 and an empty INJECT_TEXT keepalive every CONTROL_KEEPALIVE_INTERVAL_MS (currently 3s). Prevention does not replace real disconnect recovery.
• Reconnect after explicit exit: inspect cleanup trigger, socket-close classification, and cancellation of old reconnect work.
• One management feature fails: inspect its command, permission, parsing, or ROM difference instead of promoting it to remote-session failure.

Minimum evidence

• Reproduction steps, expected result, and actual result.
• Controller and target Android/device plus connection transport.
• Redacted session configuration, candidate order, and actual winner.
• Complete relevant logs from before the action through post-failure cleanup, not only the last exception.
• SessionState, component snapshot, SCID/port/socket set.
• Topic-specific codec/size/Surface or management-command facts.

Fix acceptance

• Code or tests explain the root cause; it did not merely disappear after retry.
• Failure and cancellation clean resources completely, with healthy ADB retained only according to ownership rules.
• The fix preserves scrcpy socket order and creates no second state system.
• A minimal automated regression exists; hardware/ROM behavior has an explicit device matrix.
• Logs diagnose without exposing secrets, and current wiki facts are updated.