Reporting a Problem

PolyKybdHost writes several logs, split between the tray app and the background daemon. Two entries under Help & About collect them for you.

Entry	Use it when
Report a Problem…	You want to file a bug. Describe what happened; it collects the logs and opens a pre-filled GitHub issue.
Collect logs…	You just need the log file — to send by email or chat, to attach to an existing issue, or to read yourself.

Report a Problem

Help & About → Report a Problem…

1. Describe what went wrong, and optionally what you expected instead.
2. Pick how far back the logs should reach (the default is the last hour — a problem you are reporting now is usually minutes old).
3. Press Create Report….

PolyKybdHost then saves a log file to your Downloads folder, puts the finished report on your clipboard, and opens a pre-filled GitHub issue in your browser. Nothing is sent until you press Submit there.

You do the last step yourself: drag the saved log file into the comment box before submitting. The app deliberately does not upload it for you — an attachment is a file you can open and look at first, which pasted log text is not. The dialog’s Show Log File button reveals it in your file manager.

Tip

The report body is on your clipboard either way. If your browser doesn’t open, or the report is too long for GitHub to pre-fill, just open a blank issue and paste.

If the host cannot detect the keyboard at all

The diagnostics block gets the firmware and protocol versions from the keyboard, so a report filed while nothing is connected does not include them. Read them on the keyboard instead: open the settings layer, tap More…, and the status display shows the firmware, protocol and hardware versions — on the split72, uptime and split-link health as well — see board info on the status display.

What the report contains

The issue body contains your description plus a short diagnostics block — app and firmware versions, protocol version, operating system and architecture, run mode, the connected keyboard, (on Linux) the desktop session, since that decides how window tracking works, and a one-line summary of the crash log. It contains no log lines; they are only in the attached file.

That crash-log line is a count, not a diagnosis:

Crash log        : 1 session(s), 0 clean exit(s), 1 native fault dump(s), newest marker 2026-08-15 09:00:00

A session without a clean exit is not a crash by itself. The app writing the report is one such session, and so is a running daemon.

Paths are stripped of your account name, and on a forwarder machine the address of the computer it forwards to is masked — an issue tracker is public.

Window titles

Mask window titles is ticked by default here. PolyKybdHost reads window titles constantly (that is how overlays follow the focused app), and a title can name a document. With masking on, application names are kept — which is what overlay problems are actually diagnosed from — and the titles themselves are replaced with placeholders.

Untick it only when the problem is the wrong overlay appearing for a particular window, and look at the file before you attach it.

When the app notices a problem itself

PolyKybdHost watches the keyboard’s console for known failure messages and its own log for errors. The first time one appears in a session, it shows a dialog that offers Report a Problem. Nothing is sent unless you send it.

Three settings control it, under Settings → Problem:

Setting	Default	What it does
Scan Keyboard Console	on	Watch the keyboard’s console.
Scan Host Logs	on	Watch this app’s own log.
Scan Level	Errors	Errors and warnings also counts warnings.

When the keyboard firmware crashes

Firmware protocol v16+

A keyboard half that hits a hardware fault or stops responding no longer stays stopped until you reconnect it: the firmware records what it was doing, restarts itself, and keeps a record of the crash. Each time the keyboard boots, PolyKybdHost reads that record from both halves and shows an alert for any crash it has not shown you before, so you find out about a crash without ever opening a log.

The dialog says which half crashed, what kind of crash it was (a fault, an unexpected exception, or a watchdog restart after a hang), what the firmware was doing at the time and how long it had been running, and offers two ways to report it:

Button	What it does
Report on GitHub…	Opens Report a Problem with the crash already written into the description — the log bundle and the pre-filled issue work exactly as above.
Copy to Clipboard	Copies the crash details plus the host diagnostics as plain text, to paste into a chat, an e-mail or an existing issue.

Dismiss only closes the alert; it does not clear the record. To read it again later, choose Help & About → Read keyboard crash record: it reads both halves, shows what they hold, older records included, and copies the text to the clipboard for a bug report. From a terminal, polyctl crash show does the same while the host daemon is running (--slave for the link-side half, crash clear to delete it). The keyboard keeps working meanwhile; the alert is information, not an error you have to act on.

Note

The firmware records crashes from protocol 16 on. Reading the record on every keyboard boot needs PolyKybdHost 1.14.0 or later.

Catching a crash that happens only occasionally

Firmware protocol v22+host 1.15.0+

Some problems show up only at startup, and only occasionally: the keyboard stops on its boot screen and recovers by itself a few seconds later. Waiting for that to happen again is slow. The boot-loop test makes it happen on purpose.

Turn on developer mode (Settings → Developer → Mode) and choose Developer → Firmware → Boot-loop test…. Pick a number of rounds (up to 9999) and start it. The app reboots the keyboard, waits for it to start again and reads its crash record, then does it again. It stops at the first boot that left a crash record, at a boot that does not finish within a minute, or after the last round. Each round takes a few seconds, and the keyboard does not type while the test runs.

From a terminal, polyctl bootloop --rounds 200 does the same, and polyctl bootloop --cancel stops it. polyctl reboot restarts both halves once. A reboot saves nothing, so a long run does not wear out the keyboard’s settings storage.

When the test stops on a crash, attach its result to your report: it names the round and contains the crash record.

Collect logs

Help & About → Collect logs…, or the Collect Logs… button in the log viewer.

Choose a timeframe — 15 minutes, 1 hour, 24 hours (the default), 7 days, or everything on disk — and then either:

• Save Bundle… — write a .zip you can attach anywhere, or
• Copy to Clipboard — paste the same content straight into a chat window.

The .zip contains every log file merged in chronological order, a diagnostics.txt describing your setup, your settings with any secrets removed, and a README.txt stating the timeframe and whether titles were masked.

The timeframe applies to the rotating logs. Crash markers and native fault dumps are always included in full, whatever timeframe you pick.

Caution

Masking is off by default here, because a bundle you inspect yourself is a different decision from one meant for a public issue tracker, and a first support request with everything masked usually has to be repeated. Tick Mask window titles if you would rather not include them.

From the command line

polyctl logs does the same things without the GUI. Unlike every other polyctl command, it works with the host stopped, so you can use it when the app will not start.

# Write a support .zip of the last 24 hours
polyctl logs bundle

# A specific window and destination, with window titles masked
polyctl logs bundle --since 2h --redact -o ~/polyhost-logs.zip

# Print recent lines to the terminal (pipe it anywhere)
polyctl logs show --since 30m --lines 200

# Just list the log files that were found, and how big they are
polyctl logs paths

--since accepts 30m, 2h, 7d or all. If the logs are somewhere unusual — a daemon started from a different working directory — give their folder with --log-dir.

On the forwarder

Both entries are also under Help & About in the forwarder’s tray menu. The forwarder runs on a different machine from the keyboard, so its logs never appear in a bundle collected on the keyboard side. Its reports say FORWARDER mode on the first line.

If overlays are not following a forwarded window, collect from both machines — If it does not work lists which log shows which symptom.

Where the logs are stored

The log viewer (Help & About → Log file…) shows the same files in a window, with the daemon’s own activity under the Daemon Log tab and anything the app recorded about a crash under Crash Log. A tab appears once its file exists, so the set you see is whatever this machine has actually written. To record more detail, start the app with --dev or --dev 2 — see Using the Tray App.