Belajar Zellij - Troubleshooting & Debugging

#Pendahuluan

Setelah episode 22 mengamankan workspace, episode 23 ini menjawab pertanyaan yang pasti pernah menghantui kalian: apa yang harus dilakukan ketika Zellij tidak berperilaku seperti seharusnya? Series Belajar Zellij masuk ke babak Troubleshooting & Debugging — keterampilan yang paling sering diremehkan, tetapi paling menentukan apakah Zellij terasa profesional atau terasa berantakan.

Zellij adalah sistem yang kompleks: server client-server, terminal emulation untuk setiap pane, plugin WASM yang berjalan bersamaan, dan protokol komunikasi di antaranya. Karena kompleksitas ini, gejala yang terlihat sering menipu. Plugin yang tidak muncul bisa berarti path salah, WASM gagal dimuat, atau konfigurasi tidak di-reload. Warna yang tampak aneh bisa berarti TERM salah, terminal emulator tanpa true color, atau tema yang tidak dimuat. Gejala yang sama, akar penyebab yang berbeda.

Episode 23 membekali kalian metodologi debugging yang sistematis: membaca log Zellij lewat RUST_LOG dan ~/.cache/zellij/, mendiagnosis plugin yang tidak muncul, memperbaiki warna dan masalah TERM, menyelesaikan konflik keybind, menginspeksi session dari luar dengan zellij action, dan mereproduksi masalah dengan layout minimal. Setelah episode ini, kalian tidak lagi menebak-nebak — kalian mencari bukti.

Satu hal yang perlu diluruskan sejak awal: debugging bukan tentang menghafal daftar solusi, melainkan tentang urutan penyelidikan. Zellij memberi kalian tiga lapis sumber informasi — log, state, dan reproduksi — dan ketiganya saling melengkapi. Log memberi tahu apa yang terjadi secara internal, state memberi tahu kondisi session saat ini, dan reproduksi memberi tahu variabel mana yang sebenarnya berperan. Ketika satu lapis tidak menjawab, turun ke lapis berikutnya. Pola pikir inilah yang akan kalian bawa sepanjang episode ini.

#Log Zellij dan RUST_LOG

Ketika Zellij berperilaku aneh, log adalah sumber kebenaran pertama. Zellij menulis log ke direktori cache ~/.cache/zellij/, dan tingkat detailnya dikendalikan environment variable RUST_LOG. Semakin tinggi level, semakin banyak informasi yang direkam — dan semakin banyak pula kebisingan.

Level	Kegunaan
`error`	Hanya kesalahan fatal
`warn`	Error plus peringatan
`info`	Informasi normal startup dan shutdown
`debug`	Detail alur kerja antar komponen
`trace`	Semua detail, termasuk pergerakan karakter

RUST_LOG harus diset sebelum Zellij dimulai, bukan setelahnya — log hanya merekam apa yang terjadi selama proses hidup. Untuk sesi debugging yang sibuk, trace adalah pilihan paling informatif, meskipun menghasilkan file besar.

Jalankan Zellij dengan log trace

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

Note

RUST_LOG berlaku untuk proses Zellij itu sendiri, bukan untuk shell di dalam pane. Jadi untuk men-debug masalah renderer, keybind, atau plugin, set RUST_LOG saat menjalankan zellij dari luar — bukan di dalam pane yang sudah berjalan. Kalian tidak akan melihat log jika hanya mengekspor variabel di pane.

Saat menelusuri log, carilah baris yang menyebut komponen yang sedang bermasalah: zellij::server untuk masalah session, zellij::client untuk masalah input dan render, serta komponen plugin untuk masalah UI. Mulai dari warn, lalu naikkan ke debug dan trace jika petunjuk belum jelas. Di file yang besar, gunakan pencarian untuk menyaring baris yang relevan — misalnya nama plugin yang bermasalah atau kata kunci error — daripada membaca seluruh isi log.

RUST_LOG=trace zellij

Pola kerja yang disarankan: jalankan Zellij dengan level warn untuk kerja normal, dan naikkan ke debug atau trace hanya ketika ada masalah. Dengan begitu, file log tidak membengkak tanpa perlu dan petunjuk yang kalian cari tidak tenggelam di antara jutaan baris. Setelah masalah selesai, kembali ke level rendah agar log tetap ringan.

#Plugin Tidak Muncul

Plugin yang tidak muncul adalah salah satu masalah paling umum. Gejalanya beragam: pane kosong, tab-bar kehilangan ikon, atau plugin custom tidak pernah tampil sama sekali. Sebelum menyalahkan kode plugin, periksa penyebab paling dasar dalam urutan ini.

Pertama, path. Path plugin di layout atau konfigurasi relatif terhadap lokasi file tersebut. Jika kalian memindahkan layout ke direktori lain, path relatif ikut berubah dan plugin gagal dimuat. Gunakan path absolut jika layout berpindah-pindah. Kedua, WASM gagal dimuat. Plugin yang di-build dengan target atau toolchain salah tidak akan berjalan; pastikan target wasm32-wasi atau wasm32-unknown-unknown sesuai dengan versi Zellij. Ketiga, konfigurasi tidak di-reload. Perubahan di config.kdl atau layout tidak otomatis berlaku di session yang sedang berjalan.

Setelah memperbaiki kode atau path, muat ulang plugin tanpa membuang session:

Muat ulang plugin setelah perbaikan

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

Tip

Untuk menguji plugin custom, jangan langsung menaruhnya di layout produksi. Jalankan dengan layout satu pane dan muat plugin secara manual dengan start-or-reload-plugin. Dengan begitu, error WASM atau path yang salah terlihat jelas di layar, bukan tersembunyi di antara puluhan baris layout.

Jika semua langkah di atas tidak berhasil, buka log dengan RUST_LOG=zellij::plugins=trace zellij dan cari pesan yang menyebutkan file plugin. Biasanya log menuliskan alasan konkret — file tidak ditemukan, format salah, atau plugin melempar error saat initialize.

#Warna Salah dan Masalah TERM

Gejala warna bermasalah sangat khas: warna tampak pudar atau berbeda dari yang diharapkan, blok tema tidak cocok, teks tampak berantakan, atau garis tabel tidak sejajar. Penyebab nomor satu hampir selalu TERM yang tidak sesuai dengan terminal emulator sebenarnya.

TERM memberi tahu aplikasi — termasuk Zellij — kemampuan apa yang tersedia: berapa warna, mendukung true color atau tidak, dan bagaimana mengontrol kursor. Jika TERM diset ke nilai yang lebih rendah dari kemampuan terminal, Zellij akan menarik kemampuan dan tampilan jadi jelek. Jika diset ke nilai yang lebih tinggi, kontrol terminal bisa rusak total.

Perbaiki TERM dan verifikasi environment

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

zellij setup --check menjalankan pemeriksaan environment Zellij: terminal, warna, dan konfigurasi. Output hijau berarti siap; output merah menunjukkan bagian yang perlu dibenahi. Periksa juga bahwa terminal emulator kalian benar-benar mendukung true color — TERM=xterm-256color tidak otomatis berarti terminal mengirim 24-bit color.

Note

Masalah warna sering disalahkan pada tema, padahal akar masalahnya ada di lapisan bawah. Urutan pemeriksaan yang benar: pastikan terminal emulator mendukung true color, set TERM yang tepat, jalankan zellij setup --check, baru kemudian ganti tema. Mengganti tema sebelum memverifikasi lapisan bawah hanya memperbaiki gejala, bukan penyebab.

Kasus lain yang serupa: sesi yang dipindahkan dari satu terminal ke terminal lain via attach bisa tampil aneh karena kemampuan keduanya berbeda. Detach semua client, set TERM yang sama di keduanya, lalu attach kembali. Dan ingat, TERM berbeda dengan true color — TERM=xterm-256color memberi tahu aplikasi bahwa 256 warna tersedia, tetapi warna 24-bit yang benar-benar indah bergantung pada dukungan terminal emulator itu sendiri. Dua hal ini sering disamakan, padahal berada di lapisan yang berbeda.

#Konflik Keybind

Gejala konflik keybind terasa seperti "shortcut tidak jalan" — kalian menekan kombinasi tombol dan yang terjadi adalah sesuatu yang tidak diharapkan, atau tidak terjadi apa-apa. Sumber konflik bisa bermacam-macam: shell, editor, plugin, atau dua level Zellij seperti di episode 21.

Kombinasi	Perilaku di Zellij	Sering Bentrok Dengan
`Ctrl+d`	Menutup pane (`ClosePane`)	EOF dan logout di shell
`Ctrl+b`	Prefix Tmux mode	Page-up di vim dan editor lain
`Ctrl+p`	Masuk Pane mode	Command palette di editor

Langkah pertama diagnosis adalah mengidentifikasi siapa yang menangkap tombol. Tekan Ctrl+p lalu ? di dalam session untuk melihat daftar keybind Zellij, atau baca konfigurasi default dengan zellij setup --dump-config. Jika kombinasi yang kalian tekan ada di daftar, Zellij yang menangkapnya; jika tidak, kemungkinan besar shell atau editor yang mengganggu.

Setelah tahu pelakunya, lepaskan atau pindahkan keybind yang bertabrakan lewat block keybinds:

config.kdl — lepaskan dan ikat ulang keybind yang bentrok

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

Konflik juga bisa datang dari plugin yang memakai keybind global. Jika masalah muncul setelah memuat plugin tertentu, uji tanpa plugin tersebut untuk mengisolasi penyebabnya. Bagi yang bermigrasi dari tmux, perlu diingat bahwa Zellij menawarkan Tmux mode dengan prefix Ctrl+b — tetapi prefix itu sendiri bisa bentrok dengan shortcut editor yang memakai Ctrl+b. Dalam kasus ini, pertimbangkan untuk memakai mode asli Zellij yang mode-based, atau remap prefix Tmux mode ke kombinasi lain yang tidak terpakai.

#Inspeksi dengan zellij action

Beberapa masalah lebih mudah dilihat dari luar session daripada dari dalam. Di sinilah zellij action berperan: ia memberi kalian akses untuk memeriksa state session tanpa harus berada di dalamnya. Tiga perintah yang paling berguna untuk debugging adalah list-sessions, dump-layout, dan dump-screen.

Inspeksi state dari luar session

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

zellij list-sessions menampilkan session yang ada beserta statusnya — cara cepat memastikan session masih hidup atau sudah mati. zellij action dump-layout mencetak layout session saat ini: tab, pane, ukuran, dan command yang berjalan. Ini sangat berguna ketika layout tidak tampil seperti yang didefinisikan — kalian bisa melihat apa yang benar-benar terjadi, bukan apa yang kalian harapkan.

zellij action dump-screen mencetak isi pane (screen dan scrollback) ke stdout. Redirect ke file memungkinkan kalian menelusuri output panjang, men-diff hasil sebelum dan sesudah perubahan, atau memeriksa error yang tergulir keluar layar. Untuk debugging layout, dump-layout dan dump-screen adalah pasangan ideal: satu menunjukkan struktur, yang lain menunjukkan isi.

#Reproduksi dengan Layout Minimal

Langkah terakhir adalah kebiasaan yang membuat semua debugging lebih mudah: mereproduksi masalah dengan setup sekecil mungkin. Semakin banyak variabel — konfigurasi penuh, puluhan plugin, tema custom — semakin sulit menemukan akar masalah. Layout minimal memangkas variabel itu sampai tersisa satu.

Layout minimal untuk reproduksi

layout {
    pane command="bash"
}

Mulailah dengan urutan berikut: (1) jalankan Zellij tanpa konfigurasi kustom dan lihat apakah masalah muncul — jika tidak, masalah ada di konfigurasi kalian; (2) tambahkan layout minimal dengan satu pane dan cek ulang; (3) tambahkan fitur satu per satu — tema, plugin, keybind — sampai masalah muncul; (4) fitur terakhir yang ditambahkan adalah tersangka utama.

Important

Isolasi variabel adalah inti debugging Zellij. Jangan menguji masalah plugin dengan konfigurasi penuh, dan jangan menguji masalah tema dengan RUST_LOG yang salah. Buat baseline sesederhana mungkin, lalu bisect dengan menambah satu perubahan di setiap percobaan. Pendekatan ini mengubah tebak-tebakan menjadi proses yang bisa diulang.

Metode yang sama berlaku untuk masalah yang hanya muncul di mesin tertentu: catat TERM, terminal emulator, versi Zellij, dan versi OS, lalu reproduksi di mesin kalian dengan lingkungan yang disalin. Jika masalah tidak muncul di tempat lain, perbedaannya hampir pasti ada di lingkungan, bukan di Zellij.

#Kesalahan Umum (Common Pitfalls)

Menghapus log atau cache sebelum membacanya. Bukti terpenting hilang lebih dulu. Solusi: salin file log ke lokasi lain sebelum membersihkan ~/.cache/zellij/.
Menyet RUST_LOG di dalam pane. Variabel berlaku untuk proses Zellij, bukan shell di pane. Solusi: set sebelum menjalankan zellij dari luar.
Menguji dengan konfigurasi kustom yang menutupi masalah. Bug tersembunyi di balik setting yang kalian lupa. Solusi: selalu reproduksi dengan default atau layout minimal terlebih dahulu.
Menyalahkan plugin padahal path yang salah. Gejala yang sama, akar yang berbeda. Solusi: gunakan path absolut dan muat ulang dengan start-or-reload-plugin sambil mengamati log.
Tidak memverifikasi lapisan terminal. Mengganti tema saat TERM salah hanya memperbaiki gejala. Solusi: verifikasi true color, set TERM yang tepat, lalu jalankan zellij setup --check.

#Penutup

Episode 23 melatih kalian berpikir seperti debugger: log Zellij lewat RUST_LOG dan ~/.cache/zellij/ sebagai sumber kebenaran, diagnosis plugin yang tidak muncul dari path hingga WASM, perbaikan warna dan masalah TERM, penyelesaian konflik keybind dengan identifikasi pelaku yang tepat, inspeksi session dari luar via zellij action, dan reproduksi dengan layout minimal untuk mengisolasi variabel.

Poin yang harus kalian bawa:

Log adalah bukti; RUST_LOG harus diset sebelum Zellij dimulai.
Plugin yang tidak muncul: cek path, WASM, lalu reload — jangan buru-buru menyalahkan kode.
TERM dan true color adalah fondasi tampilan; periksa sebelum mengganti tema.
Konflik keybind diselesaikan dengan mengidentifikasi pelaku, bukan menebak.
Reproduksi minimal mengubah debugging dari tebakan menjadi proses yang bisa diulang.

Dengan keterampilan debugging ini, masalah Zellij tidak lagi menakutkan — setiap gejala adalah petunjuk. Di episode 24 selanjutnya kita naik ke level performa: Performance Optimization — mengatur scroll_buffer_size dan scrollback_lines_to_serialize, mengurangi beban renderer dengan tema sederhana, menjaga banyak session dan plugin tetap responsif, serta manajemen sumber daya di mesin terbatas. Sampai jumpa di episode 24, dan biarkan workspace kalian berjalan cepat.