#3292·Solaar

UnicodeDecodeError crashes pair/show/unpair when a device name contains invalid UTF-8

Author: s0up4200Created Aug 8, 2026Updated Aug 8, 2026

Information

  • Solaar version: 1.1.20
  • Distribution: Arch Linux (Omarchy)
  • Kernel version: Linux 7.1.4-arch1-1 x86_64 GNU/Linux
  • Output of solaar show: crashes — that is this bug (tracebacks below; full working output after the fix at the end)

Describe the bug A device whose name field contains invalid UTF-8 makes Solaar crash with UnicodeDecodeError in three separate code paths, so the device cannot be paired, listed, or unpaired.

My MX Master 3S had c3 23 (invalid UTF-8: 0xc3 lead byte followed by 0x23) in its user-writable DEVICE FRIENDLY NAME (0x0007) field — likely a mangled rename from another OS. The Bolt receiver copies this name into its own registers at pairing time, so the bad bytes surface both from receiver register reads and from the live HID++ 2.0 feature:

  1. solaar pair → crash in notifications.py handle_device_discovery (device_name decode), aborting Bolt pairing entirely:
  File ".../logitech_receiver/notifications.py", line 534, in handle_device_discovery
    receiver.pairing.device_name = notification.data[3 : 3 + notification.data[2]].decode("utf-8")
UnicodeDecodeError: 'utf-8' codec can't decode byte 0xc3 in position 0: invalid continuation byte
  1. solaar show / solaar unpair → crash in receiver.py BoltReceiver.device_codename:
  File ".../logitech_receiver/receiver.py", line 499, in device_codename
    return codename.decode("ascii")
UnicodeDecodeError: 'ascii' codec can't decode byte 0xc3 in position 0: ordinal not in range(128)
  1. solaar show (after working around 2) → crash in hidpp20.py get_friendly_name:
  File ".../logitech_receiver/hidpp20.py", line 1894, in get_friendly_name
    return name.decode("utf-8")
UnicodeDecodeError: 'utf-8' codec can't decode byte 0xc3 in position 0: invalid continuation byte

Raw Bolt receiver register dump (RECEIVER_INFO / BOLT_DEVICE_NAME + n, part 0x01) showing the healthy slot vs the corrupted one — same parser, one decodes fine, the other has a 2-byte garbage name with a valid length byte:

slot 1 part 0x01: 61 01 0d 4d 58 20 4d 61 73 74 65 72 20 33 20 42   ("MX Master 3 B", len 13)
slot 2 part 0x01: 62 01 02 c3 23 00 00 00 00 00 00 00 00 00 00 00   (len 2, invalid UTF-8)

The same c3 23 was also returned live by the device via DEVICE FRIENDLY NAME (0x0007), confirming the device itself carried the bad bytes (fixed on my unit by calling 0x0007 fn 4 ResetFriendlyName — after which everything works and stock Solaar shows Friendly Name: MX Master 3S).

To Reproduce Steps to reproduce the behavior:

  1. Have a device whose friendly-name field contains invalid UTF-8 (mine arrived in this state; the field is writable via HID++ 0x0007 fn 3)
  2. Attempt solaar pair with a Bolt receiver → traceback 1, pairing aborts
  3. If the device is already paired, run solaar show or solaar unpair N → tracebacks 2/3

Additional context The name is display-only in all three paths, so a strict decode turns a cosmetic problem into an unusable device. I have a 3-line fix (decode with errors="replace") that I will submit as a PR referencing this issue.

  • Contents of ~/.config/solaar/config.yaml: not relevant to this bug (crash occurs before/independent of settings)
solaar show output after fixing the device's name field (hardware details of the affected device)
Bolt Receiver
  Device path  : /dev/hidraw12
  USB id       : 046d:C548
  Has 2 paired device(s) out of a maximum of 6.

  2: MX Master 3S
     WPID         : B034
     Codename     : MX Master 3S
     Kind         : mouse
     Protocol     : HID++ 4.5
     Model ID:      B03400000000
     Firmware: 1 BL1 69.00.B0003 B03438FCA4E6
     Firmware: 0 RBM 22.00.B0003 B03438FCA4E6
         7: DEVICE FRIENDLY NAME   {0007} V0
            Friendly Name: MX Master 3S