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.
1. Run auri-doctor first
Section titled “1. Run auri-doctor first”The combined package installs this command. With no arguments it is read-only and changes nothing:
auri-doctorFour flags:
| Command | What it does |
|---|---|
auri-doctor | Prints a link report and ends with the exact command to run next |
auri-doctor --runtime | Expands the Runtime line into a full snapshot: libauri, panel, lexicon, config paths, plus ignored variables and anomalies |
auri-doctor --repair-xim | Enables 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-caret | Installs and enables the GNOME Shell caret-tracking extension. After running it you must log out and back in once |
auri-doctor --enable-jbr-wayland | Optional: 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.
2. How to read the report
Section titled “2. How to read the report”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:
| Field | Expected |
|---|---|
DISPLAY | set; under a Wayland session usually an XWayland display such as :1 |
XMODIFIERS | @im=ibus |
IBUS_ENABLE_SYNC_MODE | 1 in the environment of the ibus-x11 process |
| XIM selection | @server=ibus has an owner |
ibus-x11 process | running (/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.
3. Where the log is
Section titled “3. Where the log is”~/.local/state/auritype/auritype.logThe directory comes from $XDG_STATE_HOME; when that is unset it defaults to ~/.local/state.
| Item | Value |
|---|---|
| Directory permissions | 0700 (only you can enter) |
| File permissions | 0600 |
| Rotation | 5 MiB per file, 3 backups kept |
| Startup cleanup | at most 20 log files; anything older than 30 days is removed |
| Level | INFO 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.
4. Environment variables
Section titled “4. Environment variables”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.
| Variable | Purpose |
|---|---|
AURI_CABI_LIB | Path to the libauri shared library |
AURITYPE_PANEL | Path to the candidate panel executable |
AURI_LEXICON_ROOT | Root directory of the lexicon |
AURI_CONFIG_PATH | User config file, overriding the default ~/.config/auritype/config.toml |
AURI_SYSTEM_CONFIG_PATH | System template config |
AURI_DEBUG | When truthy, logs go to DEBUG and the full Runtime snapshot is printed |
AURI_ATSPI | Accessibility (assistive technology) switch |
AURI_W0_WAIT_MS | Wait in milliseconds before the first render |
AURI_PANEL_LOG | Where 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.
5. Reload, pollution, and rollback
Section titled “5. Reload, pollution, and rollback”Reload the engine after installing or updating:
ibus restartRun 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:
ibus exitibus-daemon -drxDo 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.
sudo apt remove --purge auritype