Troubleshooting

Quick fixes for the most common issues. If a problem is not listed here, check the scan log for error status entries.

Reader not listed in the dropdown

1. Click Refresh next to the reader dropdown — this rescans all PC/SC readers the OS currently exposes.
2. Unplug and replug the reader, then click Refresh again.
3. Confirm the OS recognises the reader independently (Device Manager → Smart Card readers on Windows; system_profiler SPUSBDataType on macOS).
4. Install or reinstall the device driver if the OS does not list the reader.
5. See Readers for the full reader-selection workflow.

Nothing is typed when a card is placed

Typing is disarmed. The app starts disarmed by default. Click the Typing active toggle to arm it. The toggle must show an active / armed state before any card scan will produce keyboard output. See Typing & Safety.

macOS: Accessibility permission not granted. macOS requires the Accessibility permission for any app that synthesizes keystrokes into other apps. If the permission is missing, the app displays a banner with a button that opens System Settings → Privacy & Security → Accessibility directly. Enable nfc-keyboard-emulator there, then try scanning again. See Installation for step-by-step instructions.

UID is formatted incorrectly — wrong case, byte order, or missing prefix

The output format (case, separator, byte order, prefix, trailing key) is configurable. Open the Options view and adjust the settings. A live preview updates immediately. See Output Format.

Windows SmartScreen warning on launch

The Windows release is unsigned. SmartScreen blocks unsigned executables by default. Click More info → Run anyway to proceed. See Installation for the full steps.

macOS: “app can’t be opened” / Gatekeeper block

Note

This only occurs with an unsigned build. Signed and notarized releases open without warnings.

If you downloaded an unsigned build, right-click (or Control-click) the app in Finder and choose Open from the context menu. Confirm the dialog that appears. You only need to do this once.

Reviewing or exporting past scans

Open the Log view. Every scan since the app started is listed with its timestamp, reader name, UID, and status. Use Export CSV to save the log to a file. See Scan Log.