Troubleshooting
Relevant source files
The following files were used as context for generating this wiki page:
This page defines the troubleshooting procedures and diagnostic requirements for LuCI Mobile. It covers common connection failures, router-side dependencies, and development-time analysis to ensure the Flutter client successfully communicates with the OpenWrt LuCI RPC interface.
Troubleshooting efforts focus on three primary areas: network connectivity, router module verification, and application-level stability. Correcting these issues ensures features like the real-time dashboard and client management function as intended.
Sources: README.md:1-10, fastlane/metadata/android/en-US/full_description.txt:1-5
Connectivity and Authentication Issues
Connection failures often stem from incorrect network configurations or insufficient user permissions on the OpenWrt router.
Network Path Verification
If the application fails to connect to a router:
- Open the router's address in a mobile browser to verify the network path.
- Check the protocol scheme (HTTP vs. HTTPS).
- Confirm the port number and any active firewall rules.
- Verify VPN routes if accessing the router from an external network.
Sources: README.md:94-95, fastlane/metadata/android/en-US/full_description.txt:30-31
Login Failures
When login attempts fail:
- Verify the username and password match the LuCI credentials.
- Ensure the user account has administrator permissions within the LuCI web interface.
- Check if the router uses a self-signed certificate; you must manually accept the certificate fingerprint in the app.
Sources: README.md:96, 107, fastlane/metadata/android/en-US/full_description.txt:26-27
Router-Side Diagnostics
LuCI Mobile requires specific rpcd modules to populate its interface. Missing modules result in an empty dashboard or incomplete data.
Required RPC Modules
The following modules must be installed for the app to function:
rpcd-mod-luci: Provides core LuCI RPC objects.rpcd-mod-iwinfo: Provides wireless information.
You can verify these modules using the ubus command-line utility on the router.
Sources: README.md:80-92
The diagram shows the logic for resolving empty dashboard data by verifying router-side RPC services.
Sources: README.md:83-92, 97
RPC Stalling and Concurrency
Parallel requests can sometimes cause the router's LuCI service to stall. If the app times out while a browser works correctly, limit the uhttpd request concurrency:
uci set uhttpd.main.max_requests=1
uci commit uhttpd
/etc/init.d/uhttpd restart
Sources: README.md:98-106
Development and Build Troubleshooting
Contributors must resolve static analysis and testing failures before submitting changes.
Static Analysis
The project uses strict linting rules. Use the following commands to identify code quality issues:
flutter analyze: Checks for errors, warnings, and lints.dart format .: Resolves formatting violations.
The analysis_options.yaml file enforces critical rules for resource management (e.g., close_sinks, cancel_subscriptions) to prevent memory leaks.
Sources: CONTRIBUTING.md:46-48, analysis_options.yaml:45-50
Build and Test Failures
Ensure the environment meets the minimum SDK requirements (Flutter 3.8.1 or higher) defined in pubspec.yaml.
| Symptom | Command to Diagnose |
|---|---|
| CI build failure | flutter analyze --fatal-infos |
| Logic errors | flutter test |
| Dependency issues | flutter pub get |
| UI/Layout issues | flutter run |
Sources: CONTRIBUTING.md:15-18, 126-128, pubspec.yaml:31-33
Logging and Reporting
When reporting bugs, provide the following environment details to aid in reproduction:
- Flutter version (
flutter --version). - Device or emulator details.
- Specific error messages and stack traces.
- Router configuration details.
Sources: CONTRIBUTING.md:93-100
Summary
Troubleshooting LuCI Mobile involves verifying both the mobile client's environment and the OpenWrt router's RPC configuration. Most connectivity issues resolve by ensuring rpcd modules are active and uhttpd settings are optimized for single-request stability. For developers, maintaining code health via flutter analyze and flutter test is mandatory for project stability.
Sources: README.md:108-110, CONTRIBUTING.md:156-160