MemRelay/projects/4f53c06a-c6c3-40ec-b2fc-5f019ea45fc0/curated/development/Common Issues & Remedies.md

title, type, permalink, stable_id, scope, project_id, workspace_type, usage_profile_id, preference_context, document_type, revision, source_memory_ids, source_checkpoint_ids, source_file_ids, source_git_commit, source_git_commits, source_agent_sync_ids, model_connection, model_name, source_count, source_revisions, source_dispositions, cited_source_ids, job_cited_source_ids, conflicts, supersedes, preferences, source_cursor, source_hash, prompt_version, schema_version, curation_job_id, created_at, updated_at, tags, restored_from_commit

title	type	permalink	stable_id	scope	project_id	workspace_type	usage_profile_id	preference_context	document_type	revision	source_memory_ids	source_checkpoint_ids	source_file_ids	source_git_commit	source_git_commits	source_agent_sync_ids	model_connection	model_name	source_count	source_revisions	source_dispositions	cited_source_ids	job_cited_source_ids	conflicts	supersedes	preferences	source_cursor	source_hash	prompt_version	schema_version	curation_job_id	created_at	updated_at	tags	restored_from_commit
Common Issues & Remedies	curated	main/projects/4f53c06a-c6c3-40ec-b2fc-5f019ea45fc0/curated/development/common-issues-remedies	b74934b7-77c3-4cbc-acd6-f6f7d8dc350e	project	4f53c06a-c6c3-40ec-b2fc-5f019ea45fc0	development	null	development	troubleshooting	1				de28dc8246094e2bc17cab7c764fb4d4a2da71e0	de28dc8246094e2bc17cab7c764fb4d4a2da71e0		Sub2API	git-restore	188		processed unchanged unsupported skipped 188 0 0 0	git:backend/src/handlers.rs git:backend/src/dbus.rs git:backend/src/iptables.rs git:backend/src/usb_switch.rs	git:backend/src/handlers.rs git:backend/src/dbus.rs git:backend/src/iptables.rs git:backend/src/usb_switch.rs				87	96f0e4026558c8a03161f53b392fcec7359d4d701c4f33576b44e2f308b0ec5a	2026-08-12.3	3	null	2026-08-19T18:49:42.050675+00:00	2026-09-23T14:54:59.500685+00:00	troubleshooting issues solutions	6a6a895eaf

1. Concurrent AT / DBus Commands → org.ofono.Error.InProgress

• Cause: Overlapping AT commands sent to ofono.
• Solution: Use the global serial lock (with_serial) provided in backend/src/serial.rs. All AT‑related paths in dbus.rs and handlers.rs already wrap calls with this lock.
• Reference: git:backend/src/dbus.rs.

2. Stale iptables Rules After Crash

• Cause: Crash leaves NAT/iptables rules active.
• Solution: iptables_watchdog (started after a 5 s delay) periodically flushes iptables. Ensure flush_iptables() is invoked before any data‑connection change.
• Reference: git:backend/src/iptables.rs.

3. OTA Package Corruption

• Cause: Missing files, wrong architecture, or checksum mismatch.
• Solution: Run validate_ota_package() (in backend/src/ota.rs) before install. The CI pipeline also validates checksums via scripts/pack-ota.sh.
• Reference: memory:e92dbe0b….

4. Missing Authentication on AT Gateway

• Cause: /api/at endpoint is unauthenticated.
• Remedy: Implement token‑based auth or whitelist allowed AT commands.
• Reference: git:backend/src/handlers.rs (open issue).

5. Sensitive Fields Redacted

• Cause: APN passwords, FRPC tokens stored as [REDACTED].
• Remedy: Integrate secure storage (Vaultwarden or encrypted file) and expose UI controls for entry.
• Reference: git:backend/src/config.rs, git:frontend/src/pages/Network.tsx.

6. USB Hot‑Switch Instability

• Cause: Re‑configuring configfs gadget may fail, leaving the device without USB networking.
• Remedy: Use the switch_usb_mode_advanced routine; if it fails, fallback to a reboot. Mark the UI option as experimental.
• Reference: git:backend/src/usb_switch.rs.

7. Band‑Mask Mismatch

• Cause: UI allows bands unsupported by hardware; backend rejects silently.
• Remedy: Capture the backend error response and display it in the UI; validate band selections before sending.
• Reference: git:frontend/src/pages/Network.tsx.

8. FRPC Log Growth

• Cause: Logs grow beyond 512 KB without rotation.
• Remedy: Adjust log_rotation_size in state.rs or enable compression.
• Reference: git:backend/src/state.rs.

9. CORS Wide Open

• Cause: Development CORS set to *.
• Remedy: Restrict allowed origins in production (main.rs). Add environment‑specific configuration.
• Reference: git:backend/src/main.rs.

10. No Unit Tests

• Cause: Repository lacks test suites.
• Remedy: Add Rust unit tests for utilities (utils.rs) and Jest/RTL tests for frontend components.
• Reference: Various source files.

Each troubleshooting entry is traceable to its source ID as indicated.