Troubleshooting¶

This guide provides debugging procedures and troubleshooting steps for various components of the Whitebox system.

Navigating Docker's build logs¶

Docker's build process keeps logs small and neat. However, you might need to see the full output for examination. To prevent Docker's build from effectively concealing logs, you can use BUILDKIT_PROGRESS=plain environment variable when building, for example:

BUILDKIT_PROGRESS=plain docker compose build

`exec /bin/sh: exec format error` while building containers¶

This error typically occurs when there is a mismatch between the architecture of the Docker image and the host machine, and its related Docker cache.

In case you encounter an error such as:

 > [stratux  2/10] RUN apt update &&     apt install -y     git     wget     make     libncurses5-dev     libncursesw5-dev     librtlsdr-dev     libusb-1.0-0-dev     golang     udev &&     rm -rf /var/lib/apt/lists/*:
0.827 exec /bin/sh: exec format error
------
stratux.Dockerfile:7
--------------------
   6 |     # Install dependencies
   7 | >>> RUN apt update && \
   8 | >>>     apt install -y \
   9 | >>>     git \
  10 | >>>     wget \
  11 | >>>     make \
  12 | >>>     libncurses5-dev \
  13 | >>>     libncursesw5-dev \
  14 | >>>     librtlsdr-dev \
  15 | >>>     libusb-1.0-0-dev \
  16 | >>>     golang \
  17 | >>>     udev && \
  18 | >>>     rm -rf /var/lib/apt/lists/*
  19 |
--------------------
target stratux: failed to solve: process "/bin/sh -c apt update &&     apt install -y     git     wget     make     libncurses5-dev     libncursesw5-dev     librtlsdr-dev     libusb-1.0-0-dev     golang     udev &&     rm -rf /var/lib/apt/lists/*" did not complete successfully: exit code: 255

You can try to clear the Docker build cache by running the following commands:

docker builder prune -a
docker buildx prune -a

After pruning the cache, try building the Docker image again. This should resolve the exec format error if it was caused by a cache issue.

Debugging Insta360 Connection¶

When working with Insta360 camera integration, you may encounter connection issues or need to verify device behavior. While you can use the frontend UI to get connection status and toggle device on/off to enforce reconnects. This guide focuses on using Postman and WebSocket connections to debug and test the Insta360 Wi-Fi device connection in case of any other serious issues, if they arise.

Prerequisites¶

Compatible USB Wi-Fi interface attached to your system
Insta360 camera powered on and in range
Postman installed (for API testing)

Connecting to Management Channel¶

The management WebSocket channel provides real-time updates about device status changes. Connect to it using a WebSocket client:

ws://10.42.0.1:8000/ws/management/

You'll receive live updates when devices connect, disconnect, or change state.

Testing Procedures¶

Follow these steps to verify Insta360 connection functionality:

1. Add Your Device¶

Use the create endpoint to add your Insta360 device with Wi-Fi connection settings:

POST http://10.42.0.1:8000/plugin-views/whitebox_plugin_device_manager/devices/

Request body:

{
  "codename": "insta360_x4",
  "connection_type": "wifi",
  "connection_settings": {
    "ssid": "X4 2WRTGC.OSC",
    "password": "12345678"
  }
}

Updates should appear in the management channel.

2. Check Device Status¶

Use the status endpoint with your device ID to see the current connection state:

GET http://10.42.0.1:8000/plugin-views/whitebox_plugin_device_manager/devices/wifi/status?device_id=1

3. Check Wi-Fi Interfaces¶

Use the interfaces endpoint to see all available Wi-Fi interfaces and their current usage:

GET http://10.42.0.1:8000/plugin-views/whitebox_plugin_device_manager/devices/wifi/interfaces

4. Test Disconnect¶

Hit the disconnect endpoint:

GET http://10.42.0.1:8000/plugin-views/whitebox_plugin_device_manager/devices/wifi/disconnect?device_id=1

Verify:

Device appears as disconnected in the management channel
status endpoint reflects the disconnected state
interfaces endpoint shows the Wi-Fi interface is now available

5. Test Reconnect¶

Hit the connect endpoint:

GET http://10.42.0.1:8000/plugin-views/whitebox_plugin_device_manager/devices/wifi/connect?device_id=1

Verify:

Device appears as connected in the management channel
status endpoint reflects the connected state
interfaces endpoint shows the Wi-Fi interface is in use

6. Test with Camera Power Off¶

Power off the Insta360 camera and repeat steps 3-5 above. You should see:

Connection failures when attempting to connect
Appropriate error messages in the management channel
Status endpoints reflecting the disconnected state

7. Test with Camera Power On¶

Power on the Insta360 camera and repeat steps 3-5 again. Connection should succeed and status should update accordingly.

8. Test Multiple Devices (beta, not supported fully)¶

If you have multiple USB Wi-Fi interfaces:

Add additional devices using the create endpoint
Verify each device gets assigned to a different interface
Check that the interfaces endpoint correctly shows which interfaces are in use
Ensure devices can connect/disconnect independently

Note: You won't be able to stream from multiple Insta360 cameras simultaneously as of now, but connection management should work.

9. Test Interface Unavailability¶

Try to connect more devices than you have available Wi-Fi interfaces. Verify that:

Appropriate errors are returned
Error messages indicate no available interfaces
System doesn't attempt to assign multiple devices to the same interface
Existing connections remain stable

Common Issues and Troubleshooting¶

Issue: Wi-Fi interface not detected¶

Symptoms:

Interface doesn't appear in the interfaces endpoint

Solutions:

Verify the USB Wi-Fi adapter is properly connected
Check that the adapter is compatible with your system
Check interface was able to bind to host using ip link show on the host and ensuring wlan0 & wlan1, minimum two interfaces are present
Run docker exec -it backend-dev bash and check with nmcli device wifi list ifname wlan1 to see if the adapter can scan for networks and the SSID of the Insta360 camera appears

Offline Map Bundle Debugging¶

If offline maps are not displaying correctly in the frontend, verify the runtime bundle flow.

Check Runtime Mapping¶

Confirm the runtime points to the expected country bundle URL contract:

${MAP_ASSETS_BASE_URL}/${COUNTRY_CODE}.tar.gz

Ensure MAP_ASSETS_BASE_URL and COUNTRY_CODE are set to values that match your uploaded objects.

Verify Bundle URL Availability¶

From a shell with matching environment values:

curl -I "${MAP_ASSETS_BASE_URL}/${COUNTRY_CODE}.tar.gz"

HTTP 200 responses indicate the runtime country bundle object is reachable.

Verify Object in Storage¶

Use rclone against your configured remote path to confirm the object exists:

rclone ls "<remote>:<path>/${COUNTRY_CODE}.tar.gz"

If the object is missing, upload the required country bundle(s) to the same remote path.

Shared Asset Note¶

Shared style/resources are backend-image-build-managed. Maintainers publish country bundles only.

Check Backend Logs¶

Ensure you do not see map bundle download/extract errors in backend logs:

docker compose logs -f backend

Inspect Network Requests¶

Use browser developer tools to inspect network requests for ${COUNTRY_CODE}.tar.gz and map resources. Look for 404/403 responses or CORS errors.

Monitoring and Exporting Logs¶

For post-flight debugging (especially freezes/crashes), use persistent logs and exports in addition to live docker compose logs output.

Live logs while reproducing an issue¶

# Ensure you are in the whitebox directory
cd /whitebox

# Follow service logs live
docker compose logs -f backend
docker compose logs -f stratux
docker compose logs -f frontend

List all service names with:

docker compose ps

Persistent container logs on-device (`/var/log/whitebox/...`)¶

If persistent logging has not been set up yet, enable it once:

cd /whitebox
sudo make setup-logging

After setup, Whitebox writes container logs to:

/var/log/whitebox/<whitebox-version>/wb-backend.log
/var/log/whitebox/<whitebox-version>/wb-frontend.log
/var/log/whitebox/<whitebox-version>/wb-stratux.log
and other wb-<container>.log files for services using the default Whitebox Docker syslog configuration

Quick inspection examples:

sudo ls /var/log/whitebox
sudo ls /var/log/whitebox/<whitebox-version>
sudo less /var/log/whitebox/<whitebox-version>/wb-backend.log

Frontend browser logs (DB-backed)¶

Frontend/browser logs are sent to the backend (/ws/logging/ and fallback /api/beacon/) and stored in the database as external events with source like frontend:<trace-id>.

That means they are included in standard exports as part of the database dump (unless --no-database is used).

To inspect recent frontend logs directly on-device:

docker exec -it postgres psql -U whitebox -d whitebox -c "SELECT timestamp, source, action, data->>'message' AS message FROM event WHERE source LIKE 'frontend:%' AND action LIKE 'external.log.%' ORDER BY timestamp DESC LIMIT 200;"

Export logs for post-flight analysis¶

cd /whitebox

# Default export: database + media + metadata (+ whitebox-logs if present)
sudo ./bin/export-whitebox-data.sh

# Also include raw Docker container logs and inspect data (app-logs/)
sudo ./bin/export-whitebox-data.sh --include-logs

# Also include host system logs (system-logs/)
sudo ./bin/export-whitebox-data.sh --system-logs

# Combine both when needed
sudo ./bin/export-whitebox-data.sh --include-logs --system-logs

See Backup and restore mechanism for full export/import details and archive layout.