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

## 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.*