Inspect Linux Console Scancode Mappings with getkeycodes

A key that works on one virtual console and does nothing on another is exactly what getkeycodes exists to diagnose. It prints the kernel's current scancode-to-keycode table for the active console, a read-only check that never changes a mapping.

Allow about five minutes. You need the kbd package and a local Linux virtual terminal, such as /dev/tty1 through /dev/tty63. An SSH shell, terminal emulator, container or graphical desktop terminal is not automatically a virtual console.

1. Check the Installed Command

Run the version check as your ordinary user; it is harmless and needs no sudo:

getkeycodes --version

On the machine used for this guide, the installed output is:

getkeycodes from kbd 2.6.4

The package version there is kbd 2.6.4-2ubuntu2. Your distribution may package a different release. The local manual page describes the plain command as taking no options at all, but this installed 2.6.4 binary also accepts --version: treat the output from your own binary as authoritative on that point.

2. Run the Mapping Query from a Virtual Console

Switch to a Linux virtual terminal with Ctrl+Alt+F3, or whichever function key your system uses. Log in, then run:

getkeycodes

• No arguments needed. The command takes none.
• Two ranges printed. A formatted table lists plain scancodes in hexadecimal with their keycodes in decimal, followed by the escaped e0 scancode range.
• Kernel-supplied values. The exact numbers depend on the active console and the kernel's keyboard support.
• Low range is regular. Scancodes 1 through 88 normally map to the same keycode; later entries are queried live from the kernel, and a dash means an entry was not available.

Read the table as an observation of the console mapping only, not as a translation table for X11, Wayland, USB HID usage codes, or any application-specific input library.

getkeycodes > /tmp/getkeycodes-before.txt
sed -n '1,12p' /tmp/getkeycodes-before.txt

Do not treat that saved file as a configuration file; feeding it to another command will not restore a mapping. The related setkeycodes(8) command changes the kernel mapping and carries a separate syntax and risk profile.

3. Handle the Console Error Correctly

Run the command from SSH or a graphical terminal and you may see this instead of a table:

Couldn't get a file descriptor referring to the console.

That means the program could not get a usable Linux console device in that session. It is not evidence the keyboard has an empty mapping. Repeat the test from a local virtual terminal, or an administrative recovery console that genuinely exposes one.

Running the same command with sudo only helps if permissions were the actual problem. It cannot turn an SSH pseudo-terminal or a container's standard input into a virtual console:

sudo getkeycodes

Use elevated privileges only when your system's device permissions require them; the command reads the mapping and never needs to modify files or restart a service. If it still reports the console error under sudo, stop retrying it there and move to a real virtual terminal.

4. Compare a Suspicious Key Without Changing the Mapping

Capture the table on a console where the key behaves, then on the console where it fails:

getkeycodes > /tmp/getkeycodes-working.txt
getkeycodes > /tmp/getkeycodes-failing.txt
diff -u /tmp/getkeycodes-working.txt /tmp/getkeycodes-failing.txt

Identical tables from the same kernel and console state suggest the fault sits elsewhere: check the program's input path, the desktop input stack, the keyboard layout, or the device's event stream. A changed table is evidence of different kernel console state, but it does not by itself identify which command or service caused the change.