Troubleshooting¶

If things are not working, first check the error message that was displayed (the [ERROR] line and the Next step: hint). Below are remedies organized by symptom.

Cannot install usbipd-win with winget¶

If you cannot proceed when running winget install ... dorssel.usbipd-win, because of an error like the following.

Failed in attempting to update the source: winget
0x8a15000f : Data required by the source is missing
No package found matching input criteria.

This happens when winget's package source (the package list index) has not been initialized, or is not registered for the current user profile. Resolve it in the following order.

1. Reset the source and fetch it again.

   PowerShell

   winget source reset --force
   winget source update
   

2. Re-run the install, automatically accepting the terms of use.

   PowerShell

   winget install --interactive --exact dorssel.usbipd-win --accept-source-agreements --accept-package-agreements
   

If this does not resolve the issue, install manually without winget. Download the latest usbipd-win_x.x.x.msi from usbipd-win's GitHub Releases and double-click it to install.

usbipd attach fails (no WSL distribution)¶

If you see usbipd attach failed, or the following message.

usbipd: error: There is no WSL 2 distribution running; ...

usbipd attach --wsl requires an actual WSL2 distribution (Ubuntu, in this guide). Docker Desktop's internal distribution (docker-desktop) is not recognized as an attach target.

• Install Ubuntu — If it is not installed yet, follow the steps in Install (Windows) to run wsl --install -d Ubuntu and complete the initial setup (username and password).

• Check that it is running on WSL2 — Run the following command and confirm that Ubuntu is listed with VERSION set to 2.

  PowerShell

  wsl -l -v
  

Cannot run due to a security warning¶

• "Open File - Security Warning" — Click Run.
• "Windows protected your PC" (SmartScreen) — Click More info; a Run anyway button appears, so click that. See Run (Windows) for details.

Administrator privileges error (usbipd bind failed)¶

If you see usbipd bind failed or a message that administrator privileges are required.

• start.bat requests administrator privileges when it runs. For the prompt "Do you want to allow this app to make changes to your device?", select Yes. If you accidentally selected "No", run start.bat again.

Receiver (COM port) not found¶

If you see No Septentrio COM port found or mosaic-G5 ... is not connected.

• Is the receiver connected via USB? — Reseat the cable and confirm that the receiver's PWR LED is lit red.
• Is RxTools installed? — The driver that lets the receiver be recognized as a USB serial device is provided by RxTools. If it is not installed, see Install (Windows).
• Is another application, such as RxControl, holding the COM port? — Having RxControl open occupies the COM port. Close it and try again.
• Has it already been attached to WSL? — Once attached to WSL, the COM port is no longer visible from Windows. Detach it with scripts\windows\detach.bat and try again.

SBF stream not detected¶

If you see No SBF stream detected on the receiver's ports, or both ports show 0 bytes during detection.

• Is the SBF output set to USB1? — If output is going to COM1 (the physical serial port), it will not reach the USB side. start.bat normally configures this automatically, but if you have overridden it with a manual configuration, check Appendix: Receiver Setup.
• Is QZSL6 tracking enabled? — Check whether the correction data (QZSRawL6D/E) is being output; see the same appendix.

• You see permission denied for user ... — Serial devices inside WSL (/dev/ttyACM*) can only be read by root or a user in the dialout group, and whether you are in dialout depends on the Ubuntu version and setup method. start.bat runs detection with root privileges (wsl -u root), so this error does not occur there, but it can appear if you run the detection script manually. To fix this permanently, run the following in the Ubuntu shell.

  Bash

  sudo usermod -aG dialout $USER
  

  After running it, execute wsl --shutdown in PowerShell to apply the group change, then try again.

wsl -u root bash -c 'for p in /dev/ttyACM*; do echo $p:; timeout 3 cat $p | head -c 64 | od -An -tx1; done'

Docker Desktop is not running on the WSL2 backend¶

If either of the following errors is shown when running docker run.

docker: Error response from daemon: error gathering device information while adding custom device "/dev/ttyACM0": no such file or directory

docker: Error response from daemon: ... workspace: Access is denied.

If Docker Desktop is running on the Hyper-V backend, containers run on a virtual machine separate from WSL2. Because of this, the container cannot see the receiver device attached to WSL (Ubuntu) (no such file or directory), and mounting Windows folders can also be denied access (Access is denied).

First, check whether docker-desktop is registered with the following command.

wsl -l -v

If docker-desktop is not listed, it is running on the Hyper-V backend. Follow the steps in Install (Windows) to enable Use the WSL 2 based engine, turn on Ubuntu under WSL integration, and then run start.bat again.

wsl ls /dev/ttyACM*

Container does not start¶

If you see docker run failed or docker command not found, or startup does not proceed.

• Is Docker Desktop running? — Hover over the 🐳 icon in the taskbar's hidden icons and confirm Docker Desktop running. If it is not running, start Docker Desktop and try again.
  • If the logged-in user and the administrator user are different → Run Docker Desktop as administrator
• You see ... workspace: Access is denied or ... no such file or directory — This often happens when Docker Desktop is not running on the WSL2 backend. See Docker Desktop is not running on the WSL2 backend.
• docker command not found — Docker Desktop itself is not installed. See Install (Windows).
• Port 8080 / 2101 is in use — If an existing container or another application is using these ports, startup fails. See Cannot start because a port is in use for details.
• Pulling the image is slow / fails — The first run takes a few minutes to download the image. Check your network connection and try again after a while.

• It stops right after starting — Check the logs with the following command.

  PowerShell

  docker logs mrtklib-web-ui
  

Cannot start because a port is in use¶

The container uses two ports. If either one is occupied, docker run fails and the container does not start.

The following error is displayed.

docker: Error response from daemon: Ports are not available: exposing port TCP 0.0.0.0:2101 -> 127.0.0.1:0: listen tcp 0.0.0.0:2101: bind: Only one usage of each socket address ... is normally permitted.

A previous container is still present¶

This is the most common cause. Remove it with the following command, then run start.bat again.

docker rm -f mrtklib-web-ui

Another application is using the port¶

Find the PID of the process using the port with the following command.

netstat -ano | findstr :2101

The rightmost column of the displayed line is the PID. You can check the process name with the following command.

tasklist /FI "PID eq 1234"

If you cannot close that application, see Change the port in use.

Windows has reserved the port¶

If startup fails even though netstat shows nothing, and you see an error like the following, Windows (Hyper-V / WinNAT) may have reserved the port range.

bind: An attempt was made to access a socket in a way forbidden by its access permissions.

You can check the reserved range with the following command. Run it in an administrator PowerShell (Run PowerShell as administrator).

netsh int ipv4 show excludedportrange protocol=tcp

If the displayed range includes 8080 or 2101, restarting WinNAT may release the reservation.

net stop winnat
net start winnat

If it is not released, see Change the port in use.

Change the port in use¶

Rewrite the following values, near the top of scripts\windows\lib\common.ps1, to unused port numbers.

$HostPort      = 8080   # web UI (MRTKLIB Console)
$OutPort       = 2101   # TCP/IP output of the solution

Run Docker Desktop as administrator¶

If the logged-in user and the administrator user are different, you need to run Docker Desktop as administrator. If Docker Desktop is already running, first stop it using the steps below.

Stopping Docker Desktop¶

Show the hidden icons from the ^ on the taskbar. Hover over the 🐳 icon, right-click, and click Quit Docker Desktop to exit.

Starting Docker Desktop¶

Search for Docker Desktop in the Windows Start menu, right-click it, and click Run as administrator.

If you relaunched it as administrator, note that Docker Desktop settings are saved per user, so go through Configure the Docker Desktop backend again.

UI does not open in the browser¶

• Fetching the image takes time on the first run — Even if the startup wait times out, the container may still be running. Wait a moment, then manually open http://localhost:8080.

• Check whether the container is running — Check whether mrtklib-web-ui shows Up with the following command. If it is not listed, run start.bat again.

  PowerShell

  docker ps
  

  When it is running

  PowerShell

  CONTAINER ID   IMAGE                                    COMMAND                   CREATED          STATUS                    PORTS                                         NAMES
  afa58c127340   hatognss/mrtklib-docker-ui:0.3.0-alpha   "uvicorn mrtklib_web…"   47 seconds ago   Up 46 seconds (healthy)   0.0.0.0:8080->8000/tcp, [::]:8080->8000/tcp   mrtklib-web-ui
  

  When it is not running

  PowerShell

  CONTAINER ID   IMAGE     COMMAND   CREATED   STATUS    PORTS     NAMES
  

Positioning does not start / does not reach FIX¶

• Is Path in the UI correct? — Set it to ttyACM0 (no leading /dev/ needed). The startup script always maps the port that SBF is on to /dev/ttyACM0 inside the container, so this value is fixed regardless of environment (Using the UI).
• Is the antenna obstructed? — Satellites cannot be acquired indoors or in places where the sky is blocked. Place the antenna somewhere with a clear view of the sky.
• Acquiring navigation data takes time on the first run — Wait a few minutes for positioning to start.
• Is QZSS L6 being received? — MADOCA-PPP requires the QZSS L6 correction data. Check QZS visibility (elevation) (GNSS View).