Agent reference: Common issues

Deep subsystem reference for AI assistants. Symptom → where-to-check index. Hard rules live in AGENTS.md.

Symptom	Where to check
Connection fails	ConnectionDriver, useProtocolConnection.ts, runtime/useMeshtasticRuntime.ts, runtime/useMeshcoreRuntime.ts
Empty chat/nodes offline	hydrateIdentityStoresFromDb, connect-time cache in runtimes, useDbRefresh; identity split — troubleshooting
Chat stuck / badge moves, no new rows	identityByProtocol, useActiveMeshIdentity, mergeOfflineIdentityStore; Export for GitHub — troubleshooting
BLE timeout	noble-ble-manager.ts, bleConnectErrors
Reticulum sidecar won't start	reticulum-sidecar-manager.ts, ipc/reticulum-handlers.ts, troubleshooting
Nomad hosting enabled but not serving	nomadServingApi.ts, reticulum-sidecar/src/stack/nomad_server.rs / nomad_content_source.rs, [nomad-serving] logs, nomadPageErrorHumanize.ts — troubleshooting
Reticulum interface CRUD fails	ReticulumInterfacesPanel.tsx / ReticulumStackPanel.tsx, proxyPut/proxyDelete — troubleshooting
Reticulum Remote transfer / inbound policy	RemoteTransferSection.tsx / RemoteSettingsSection.tsx, rncpTransferStore.ts / reticulumInboundPolicyStore.ts, pushRncpListenerPolicy.ts — troubleshooting
Reticulum LXST voice fails / silent	reticulumVoiceSession.ts, reticulumVoiceStore.ts, sidecar voice_session.rs; troubleshooting
Reticulum LXMF hangs with Auto + LAN hub	sidecar auto_path_policy.rs / lxmf_outbound.rs; troubleshooting
Reticulum public hub TCP fast-flap block	reticulumStackSessionTracker.ts (five stack starts in 12h), ReticulumLocalInterfaceAlertsBlock.tsx (tcp_fast_flap / unreachable hint), reticulumTcpInterfaceRecovery.ts; troubleshooting
PN Sync PATH_UNKNOWN / stuck retrieve busy	PROPAGATION_PATH_UNKNOWN gate in live.rs; Cancel → abort_transfer overlay; Host silent /get latch ownership; troubleshooting
Auto picks a bad Discovered PN	Network → Propagation Ignore for Auto (propagation_auto_blacklist); filters Auto sync + deposit only
Proxy IPC storm after wake	useReticulumInterfaceSnapshot must not refresh on announce.received; shared proxy rate-limit soft envelope
Serial port auto-rediscovery	serialPortAutoRediscovery.ts (60 s window, 5 s poll) — troubleshooting
Meshtastic MQTT text on wrong channel tab	mqtt-manager.ts (resolveMqttInboundTextChannelIndex), debug snapshot meshtastic.channelPills / channelConfigsSummary / mqttChannelKeyEntryCount — troubleshooting
Chat export fails	chat:export handler in src/main/index.ts
Support export fails	support:exportBundle in src/main/support-bundle.ts; App tab Export for GitHub / Export for Developer
Draft not restored	chatPanelProtocolStorage.ts, viewKey logic
MeshCore send blocked (message too long)	chatComposerLimits.ts (getMaxChunks = 1, splitChatMessage → null, overMaxSingle), ChatComposer.tsx — single-packet, no outbound [i/N] split; also gates room posts (getMeshcoreRoomPayloadLimit). See chat.md, parity
MeshCore "sending too fast" advisory	meshcoreSendRateNotice.ts (recordMeshcoreSend / isMeshcoreSendTooFast, MESHCORE_FAST_SEND_WARN_INTERVAL_MS), ChatComposer.tsx; non-blocking role="status", clock also fed by GIF / share-location / outbox drain (useChatOutbox.ts)
Mention picker missing	MentionAutocomplete.tsx, buildMentionCandidates
Link preview missing	fetchLinkPreview.ts, chat:fetchLinkPreview IPC; also check direct-image extension/MIME, YouTube oEmbed, and magic-byte sniff failures; previews always fetch (including while reading history)
Duplicate RF+MQTT msg	meshtasticMessageDedup.ts, Meshtastic runtime ingest
MeshCore duplicate/echo	meshcoreStoreDedup.ts, useMeshcoreRuntime.ts
Room login/post fails	meshcoreRoomLoginRpc.ts, meshcoreRoomPostRpc.ts, troubleshooting
Rooms unread vs Chat	meshcoreRoomsUnread.ts — Rooms tab badge only; orphan room SQL filtered by known Room contacts; contact delete cascades room messages (deleteMeshcoreContactOn); tombstones in meshcoreLocallyDeletedContacts.ts
MQTT decrypt / sender	mqtt-manager.ts, meshtasticMqttIdentity.ts
Remote admin fails	meshtasticRemoteAdmin.ts, key storage
S&F history garbled	meshtasticBacklogUtils.ts decode, heartbeat trigger
Garbled TEXT_MESSAGE	meshtasticBacklogUtils.ts readable-text filter
Channel URL apply	meshtasticChannelApply.ts, meshtasticUrlEncoder.ts
Header red on loss	connectionHeaderStatus.ts, mqttDisconnectIntent.ts
Sleep/wake reconnect	usePowerRecovery, systemPowerState, bleReconnectHelper, rfReconnectHelper, runtimes; Meshtastic ~4s + MeshCore ~8s stagger + up to 30s dual-Noble settle
MeshCore contact prune	meshcoreContactAgeCutoff.ts, database.ts (last_advert seconds); favorited exempt
MQTT transient after wake	src/shared/networkTransientErrors.ts, mqtt:powerSuspend / mqtt:powerResume IPC
MeshCore ping no route / priming	meshcoreTraceRoutePrime.ts, meshcoreHookPreamble.ts, meshcore.errors.pingNoRoute; troubleshooting
Repeater CLI danger / auto-ping	meshcoreRepeaterCliDanger.ts, RepeatersPanel.tsx (ensureCliRoutePrimed); repeatersPanel.cliMultiHopHint
Room vs repeater LoginFail	meshcoreRoomLoginRpc.ts (fail fast) vs meshcoreRepeaterLoginRpc.ts + meshcoreRepeaterPrefixPushRpc.ts (wait for LoginSuccess)
Renderer hung after wake	rendererHeartbeatWatchdog.ts, useRendererHeartbeat; visible stall + export mainLiveness; troubleshooting — quit fully if no [usePowerRecovery] after resume watchdog
MeshCore TCP mid-init peer FIN	useMeshcoreRuntime initConn / meshcore:tcp-*; troubleshooting
Chat hop pills missing	MeshCore: meshcoreCompanionRxPathLenToHopCount / MeshCoreProtocol / meshcoreRawPacketCorrelate / meshcoreIngest; Meshtastic: meshtasticRfHops.ts (viaMqtt / hopStart===0 omit by design)
Meshtastic SDK routing console noise	meshtasticSdkRoutingErrorConsoleHook.ts, meshtasticSdkRoutingErrorLog.ts; late Packet does not exist swallow is post-teardown only (armMeshtasticLateConfigureRetryableSwallow / rendererUnhandledRejection.ts) — do not widen to full session
All Meshtastic nodes show online after BLE connect/configure	nodeStore.ts configure replay guards, meshtasticConfigurePhase.ts, meshtasticLastHeard.ts; meshtastic.md