Skip to content

Diagnostics and logs

When output goes wrong, read this page first, then match your symptom against the FAQ. Getting Started keeps only the three most common cases; the full story is here.


The combined package installs this command. With no arguments it is read-only and changes nothing:

Terminal window
auri-doctor

Four flags:

CommandWhat it does
auri-doctorPrints a link report and ends with the exact command to run next
auri-doctor --runtimeExpands the Runtime line into a full snapshot: libauri, panel, lexicon, config paths, plus ignored variables and anomalies
auri-doctor --repair-ximEnables the user-level systemd unit auritype-xim.service and brings up the ibus-x11 bridge. For Java / IntelliJ and other XIM apps
auri-doctor --repair-gnome-caretInstalls and enables the GNOME Shell caret-tracking extension. After running it you must log out and back in once
auri-doctor --enable-jbr-waylandOptional: adds -Dawt.toolkit.name=WLToolkit to the JetBrains vmoptions file so JetBrains goes over Wayland instead of XWayland

The JetBrains section of the report is read, never modified: it lists your vmoptions files and their current state (already set or XWayland), and whether to add the line is your call.


Output is one [✓] / [!] / [✗] line at a time, in a fixed order:

Session Type — wayland or x11, with the desktop name in brackets. Only Wayland needs the caret extension.

Core Engine — the current IBus engine. It should read auritype-pinyin; anything else means you have not switched input sources yet.

Runtime — by default a single line: mode, the libauri actually loaded, and the anomaly list. mode=installed means the binaries under /usr/share/auritype; in installed mode development toolchain variables such as CARGO_TARGET_DIR are ignored. If anomalies is non-empty, re-run with --runtime.

GNOME Caret Extension (GNOME only) — the extension ID is auritype-window-origin@auritype. Three things are checked in order: whether the extension directory exists (/usr/share/gnome-shell/extensions/auritype-window-origin@auritype), whether the bus name com.auritype.CaretRoot is owned, and whether the Shell-side IBus connection is healthy (manager present, panel attached, candidate popup taken over, current engine). Files present but the bus not owned is the classic “just installed, not logged back in” — the Shell scans extension directories only at login, so the report tells you to run --repair-gnome-caret and log out and back in.

XWayland Subsystem — this block covers Java, older Electron, and anything else going through XIM:

FieldExpected
DISPLAYset; under a Wayland session usually an XWayland display such as :1
XMODIFIERS@im=ibus
IBUS_ENABLE_SYNC_MODE1 in the environment of the ibus-x11 process
XIM selection@server=ibus has an owner
ibus-x11 processrunning (/usr/libexec/ibus-x11)

If any of these fails, the report says plainly that Java/AWT applications (IntelliJ IDEA, for example) will not accept Chinese, and points at auri-doctor --repair-xim.

ibus-daemon — reported on its own line when it is not running.


~/.local/state/auritype/auritype.log

The directory comes from $XDG_STATE_HOME; when that is unset it defaults to ~/.local/state.

ItemValue
Directory permissions0700 (only you can enter)
File permissions0600
Rotation5 MiB per file, 3 backups kept
Startup cleanupat most 20 log files; anything older than 30 days is removed
LevelINFO and silent when IBus launches the engine (--ibus); DEBUG with console output when you start it from a terminal

Logs never record the composition string, the candidates, or the committed text — only engine state, link status and anomalies. For a fuller startup snapshot set AURI_DEBUG=1, or run auri-doctor --runtime; the complete dump appears only in those two places and is never written into ~/.config/auritype or any other user directory.


These change what the engine loads and where it writes. A normal install needs none of them; they are listed because “I installed the new package but it behaves like the old one” usually means a terminal inherited one of them.

VariablePurpose
AURI_CABI_LIBPath to the libauri shared library
AURITYPE_PANELPath to the candidate panel executable
AURI_LEXICON_ROOTRoot directory of the lexicon
AURI_CONFIG_PATHUser config file, overriding the default ~/.config/auritype/config.toml
AURI_SYSTEM_CONFIG_PATHSystem template config
AURI_DEBUGWhen truthy, logs go to DEBUG and the full Runtime snapshot is printed
AURI_ATSPIAccessibility (assistive technology) switch
AURI_W0_WAIT_MSWait in milliseconds before the first render
AURI_PANEL_LOGWhere the panel writes its own log

Those nine always win when set explicitly. Beyond them, running from a source tree (dev mode) lets CARGO_TARGET_DIR participate in finding candidate libraries; in an installed build it is ignored and an anomaly is logged.


Reload the engine after installing or updating:

Terminal window
ibus restart

Run it in an ordinary terminal. From an IDE or agent shell you carry CARGO_TARGET_DIR, CURSOR_*, and VSCODE_* with you, and that polluted environment passes down the whole subtree through the daemon, so the engine may load an old library from a sandbox. The production launchers unset those variables, but they cannot undo an already-polluted daemon parent.

When the daemon is already polluted, quit it and bring it back up from the clean systemd user session environment:

Terminal window
ibus exit
ibus-daemon -drx

Do not restart mid-keystroke. If the restart lands between pressing Enter and releasing it, the key-up event is lost and a terminal will keep auto-repeating Enter.

The XIM bridge is supervised by a systemd user unit. auritype-xim.service installs into /usr/lib/systemd/user/; after ibus restart its supervision loop brings ibus-x11 back within 30 seconds.

Extension changes need a new session. If the caret extension’s scripts or enabled state changed, the Shell only scans at login — ibus restart will not fix it.

Removing the package switches you back to English. The ibus-auritype prerm script walks the active graphical sessions and, for any ordinary user (UID ≥ 1000) whose engine is currently auritype-pinyin, switches them to xkb:us::eng; it also globally disables auritype-xim.service, so the engine cannot go missing after uninstall.

Terminal window
sudo apt remove --purge auritype