Learn Zellij - Troubleshooting & Debugging

#Introduction

After episode 22 secured your workspace, episode 23 answers the question that has certainly haunted you: what to do when Zellij doesn't behave the way it should? The Learn Zellij series enters the Troubleshooting & Debugging chapter — the skill most often underestimated, but the one that most determines whether Zellij feels professional or feels broken.

Zellij is a complex system: a client-server architecture, terminal emulation for every pane, WASM plugins running in parallel, and a communication protocol between them. Because of this complexity, visible symptoms often deceive. A plugin that doesn't appear could mean a wrong path, a WASM load failure, or a configuration that wasn't reloaded. Colors that look odd could mean a wrong TERM, a terminal emulator without true color, or a theme that didn't load. Same symptom, different root cause.

Episode 23 equips you with a systematic debugging methodology: reading Zellij logs via RUST_LOG and ~/.cache/zellij/, diagnosing plugins that don't appear, fixing colors and TERM issues, resolving keybind conflicts, inspecting sessions from outside via zellij action, and reproducing problems with a minimal layout. After this episode, you'll no longer be guessing — you'll be looking for evidence.

One thing to clarify from the start: debugging isn't about memorizing a list of solutions, it's about the order of investigation. Zellij gives you three layers of information — logs, state, and reproduction — and all three complement each other. Logs tell you what happens internally, state tells you the current session's condition, and reproduction tells you which variable actually plays a role. When one layer doesn't answer, descend to the next. This is the mindset you'll carry through this episode.

#Zellij Logs and RUST_LOG

When Zellij behaves strangely, the log is the first source of truth. Zellij writes logs to the ~/.cache/zellij/ cache directory, and the level of detail is controlled by the RUST_LOG environment variable. The higher the level, the more information is recorded — and the more noise as well.

Level	Use
`error`	Fatal errors only
`warn`	Errors plus warnings
`info`	Normal startup and shutdown information
`debug`	Workflow details between components
`trace`	All details, including character movement

RUST_LOG must be set before Zellij starts, not after — logs only record what happens while the process is alive. For a busy debugging session, trace is the most informative choice, even though it produces large files.

Run Zellij with trace logging

RUST_LOG=trace zellij
ls -la ~/.cache/zellij/

Note

RUST_LOG applies to the Zellij process itself, not to the shell inside the pane. So to debug renderer, keybind, or plugin issues, set RUST_LOG when running zellij from outside — not inside an already-running pane. You won't see any logs if you only export the variable inside a pane.

When tracing through the log, look for lines that mention the component currently having problems: zellij::server for session issues, zellij::client for input and render issues, and plugin components for UI issues. Start at warn, then raise to debug and trace if the clues aren't clear. In a large file, use search to filter the relevant lines — for example the name of the problematic plugin or an error keyword — rather than reading the whole log.

RUST_LOG=trace zellij

The recommended working pattern: run Zellij at warn level for normal work, and raise to debug or trace only when there's a problem. That way log files don't bloat unnecessarily and the clues you're looking for don't sink among millions of lines. Once the problem is resolved, return to a low level so logs stay lightweight.

#Plugins That Don't Appear

A plugin that doesn't appear is one of the most common problems. The symptoms vary: an empty pane, a tab-bar missing icons, or a custom plugin that never shows up at all. Before blaming the plugin code, check the most basic causes in this order.

First, the path. A plugin's path in a layout or configuration is relative to the location of that file. If you move the layout to another directory, the relative path changes and the plugin fails to load. Use absolute paths if layouts move around. Second, WASM failed to load. Plugins built with the wrong target or toolchain won't run; make sure the wasm32-wasi or wasm32-unknown-unknown target matches your Zellij version. Third, the configuration wasn't reloaded. Changes to config.kdl or a layout don't automatically apply to a running session.

After fixing the code or path, reload the plugin without discarding the session:

Reload the plugin after the fix

zellij action start-or-reload-plugin ./target/wasm32-wasi/release/my-plugin.wasm

Tip

To test a custom plugin, don't put it straight into a production layout. Run it with a single-pane layout and load the plugin manually with start-or-reload-plugin. That way, WASM errors or wrong paths are clearly visible on screen, not hidden among dozens of layout lines.

If all the steps above fail, open the log with RUST_LOG=zellij::plugins=trace zellij and look for messages that mention the plugin file. The log usually writes a concrete reason — file not found, wrong format, or a plugin throwing an error during initialization.

#Wrong Colors and TERM Issues

Color problems have very distinctive symptoms: colors look washed out or different from what you expect, theme blocks don't match, text looks garbled, or table lines aren't aligned. The number one cause is almost always a TERM that doesn't match the actual terminal emulator.

TERM tells applications — including Zellij — what capabilities are available: how many colors, whether true color is supported, and how to control the cursor. If TERM is set to a value lower than the terminal's capability, Zellij will pull back its capabilities and the display looks bad. If it's set higher, terminal control can break entirely.

Fix TERM and verify the environment

export TERM=xterm-256color
zellij setup --check
zellij

zellij setup --check runs Zellij's environment checks: terminal, colors, and configuration. Green output means ready; red output shows what needs fixing. Also verify that your terminal emulator actually supports true color — TERM=xterm-256color doesn't automatically mean the terminal sends 24-bit color.

Note

Color problems are often blamed on the theme when the root cause is in a lower layer. The correct order of checks: make sure the terminal emulator supports true color, set the right TERM, run zellij setup --check, and only then switch themes. Changing the theme before verifying the lower layers only fixes the symptom, not the cause.

A similar case: a session moved from one terminal to another via attach can look odd because their capabilities differ. Detach all clients, set the same TERM on both, then attach again. And remember, TERM is different from true color — TERM=xterm-256color tells applications that 256 colors are available, but genuinely beautiful 24-bit color depends on the terminal emulator's own support. These two are often conflated, yet they live in different layers.

#Keybind Conflicts

A keybind conflict feels like "the shortcut doesn't work" — you press a key combination and something unexpected happens, or nothing happens at all. The source of the conflict can vary: the shell, the editor, plugins, or two levels of Zellij as in episode 21.

Combination	Behavior in Zellij	Often Conflicts With
`Ctrl+d`	Closes the pane (`ClosePane`)	EOF and logout in the shell
`Ctrl+b`	Tmux mode prefix	Page-up in vim and other editors
`Ctrl+p`	Enters Pane mode	Command palette in editors

The first diagnosis step is identifying who captures the key. Press Ctrl+p then ? inside the session to see Zellij's keybind list, or read the default configuration with zellij setup --dump-config. If the combination you pressed is on the list, Zellij captures it; if not, the shell or editor is likely interfering.

Once you know the culprit, unbind or remap the conflicting keybind via the keybinds block:

config.kdl — unbind and rebind the conflicting keybind

keybinds {
    unbind "Ctrl d"
    bind "Alt d" {
        ClosePane;
    }
}

Conflicts can also come from plugins using global keybinds. If the problem appears after loading a specific plugin, test without that plugin to isolate the cause. For those migrating from tmux, remember that Zellij offers a Tmux mode with the Ctrl+b prefix — but that prefix itself can clash with editor shortcuts that use Ctrl+b. In this case, consider using Zellij's native mode-based modes, or remap the Tmux mode prefix to another unused combination.

#Inspecting with zellij action

Some problems are easier to see from outside the session than from inside. This is where zellij action comes in: it gives you access to inspect session state without being inside it. The three most useful commands for debugging are list-sessions, dump-layout, and dump-screen.

Inspect state from outside the session

zellij list-sessions
zellij action dump-layout > layout.txt
zellij action dump-screen 1 > screen.txt

zellij list-sessions shows the existing sessions along with their status — a quick way to confirm whether a session is still alive or already dead. zellij action dump-layout prints the current session's layout: tabs, panes, sizes, and running commands. This is very useful when a layout doesn't appear as defined — you can see what actually happened, not what you expected.

zellij action dump-screen prints the pane contents (screen and scrollback) to stdout. Redirecting to a file lets you search long output, diff the results before and after changes, or inspect errors that scrolled off screen. For layout debugging, dump-layout and dump-screen are the ideal pair: one shows the structure, the other shows the contents.

#Reproducing with a Minimal Layout

The last step is a habit that makes all debugging easier: reproducing the problem with the smallest possible setup. The more variables — full configuration, dozens of plugins, a custom theme — the harder it is to find the root cause. A minimal layout trims those variables down to one.

Minimal layout for reproduction

layout {
    pane command="bash"
}

Start with the following sequence: (1) run Zellij without a custom configuration and see whether the problem appears — if not, the problem is in your configuration; (2) add a minimal one-pane layout and recheck; (3) add features one by one — theme, plugins, keybinds — until the problem appears; (4) the last feature added is the prime suspect.

Important

Isolating variables is the core of Zellij debugging. Don't test a plugin problem with a full configuration, and don't test a theme problem with the wrong RUST_LOG. Build a baseline as simple as possible, then bisect by adding one change per trial. This approach turns guessing into a repeatable process.

The same method applies to problems that only appear on certain machines: note the TERM, terminal emulator, Zellij version, and OS version, then reproduce on your machine with a copied environment. If the problem doesn't appear elsewhere, the difference is almost certainly in the environment, not in Zellij.

#Common Pitfalls

Deleting logs or cache before reading them. The most important evidence disappears first. Fix: copy the log files to another location before cleaning ~/.cache/zellij/.
Setting RUST_LOG inside the pane. The variable applies to the Zellij process, not the shell in the pane. Fix: set it before running zellij from outside.
Testing with a custom configuration that masks the problem. Bugs hide behind settings you forgot about. Fix: always reproduce with defaults or a minimal layout first.
Blaming the plugin when the path is wrong. Same symptom, different root. Fix: use absolute paths and reload with start-or-reload-plugin while watching the logs.
Not verifying the terminal layer. Changing the theme while TERM is wrong only fixes the symptom. Fix: verify true color, set the right TERM, then run zellij setup --check.

#Closing

Episode 23 trained you to think like a debugger: Zellij logs via RUST_LOG and ~/.cache/zellij/ as the source of truth, diagnosing plugins that don't appear from path to WASM, fixing colors and TERM issues, resolving keybind conflicts by identifying the right culprit, inspecting sessions from outside via zellij action, and reproducing with a minimal layout to isolate variables.

The points to take away:

Logs are evidence; RUST_LOG must be set before Zellij starts.
Plugin doesn't appear: check path, WASM, then reload — don't rush to blame the code.
TERM and true color are the foundation of the display; check them before changing the theme.
Keybind conflicts are resolved by identifying the culprit, not by guessing.
Minimal reproduction turns debugging from guessing into a repeatable process.

With these debugging skills, Zellij problems are no longer scary — every symptom is a clue. In episode 24 next, we go up a level to performance: Performance Optimization — tuning scroll_buffer_size and scrollback_lines_to_serialize, reducing renderer load with a simple theme, keeping many sessions and plugins responsive, and resource management on limited machines. See you in episode 24, and may your workspace run fast.