106 lines
4.1 KiB
Markdown
106 lines
4.1 KiB
Markdown
---
|
||
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.* |