Belajar Tmux - Troubleshooting & Debugging

#Pendahuluan

Di episode 22 sebelumnya kita membangun antarmuka yang kaya: display-popup, display-menu, floating panes, dan fitur modern 3.6 sampai 3.7. Semakin banyak fitur, semakin banyak pula hal yang bisa rusak — dan pada episode ini kita mempelajari cara memperbaikinya dengan kepala dingin: troubleshooting & debugging.

Sebagai engineer, kemampuan debug bukan soal menghafal solusi, melainkan soal metode. Tmux adalah alat yang sangat kooperatif untuk di-debug: hampir semua kondisinya bisa diintrospeksi — daftar session, client, pane, binding, option, bahkan log server. Masalah jarang datang dari tmux yang "rusak"; hampir selalu dari konfigurasi, environment, atau pemahaman yang tidak lengkap. Episode ini mengajarkan kalian bertanya pada tmux itu sendiri sebelum bertanya ke internet. Semua contoh merujuk tmux 3.7b sebagai versi stabil terbaru.

#Pendekatan Diagnostik: Bertanya pada Tmux Itu Sendiri

#Tiga Pertanyaan yang Selalu Ditanyakan

Sebelum menyentuh apa pun, jawab tiga pertanyaan ini secara berurutan — 90% masalah selesai di langkah ini:

Apakah server berjalan, dan di socket mana? Jika kalian "tidak bisa menemukan session", besar kemungkinan server yang kalian tuju berbeda dari yang kalian duga.
Apa yang tmux lihat? Terminal, ukuran, status, dan option yang aktif. Gejala di layar hampir selalu berakar di sini.
Apa yang dikatakan config? Apakah perubahan kalian benar-benar dimuat? Config yang tidak di-source-file ulang tidak akan berlaku.

#list-sessions, list-clients, list-panes

Tiga perintah list adalah mata pertama:

Lihat semua session & client

tmux list-sessions
tmux ls
tmux list-clients
tmux list-panes -a

list-sessions (alias tmux ls) menampilkan session beserta jumlah window dan ukuran. list-clients menunjukkan siapa yang terhubung dan dari terminal mana — berguna saat session terasa "dipegang" orang lain. list-panes -a memperluas semua pane di semua window dan session, dan menjadi penjawab cepat pertanyaan "kenapa pane ini tidak terlihat".

#Membaca Status dan Log Server

#tmux info: Jendela ke Dalam Server

Ketika dugaan kalian habis, tmux info membuka isi server: PID, path socket, versi, terminal yang dipakai tiap client, dan banyak detail lain dalam satu dump:

tmux info - status internal server

tmux info
tmux info | grep server_pid
tmux info | grep socket_path

Baris seperti server_pid, socket_path, dan version adalah data pertama yang dibutuhkan saat melapor ke issue tracker — dan sering kali cukup untuk melihat ketidakcocokan, misalnya dua server dengan versi berbeda karena socket -L yang berbeda.

#Log Server dan show-messages

Tmux mencatat pesan dan error server pada file log: ~/.tmux-<uid>.log (misalnya ~/.tmux-1000.log). Ketika tmux "diam" tanpa alasan, log ini adalah saksi yang tidak bisa berbohong:

Baca log server tmux

tail -n 100 "$HOME/.tmux-$(id -u).log"

Di dalam session, Prefix + ~ (atau tmux show-messages) menampilkan pesan server yang tersimpan — termasuk error saat loading config. Pesan seperti .../.tmux.conf:6: unknown option langsung menunjuk baris mana yang membuat konfigurasi gagal. Mulailah debugging config dari sini, bukan dari menebak.

#display-message -p: Format Menjadi Data

Format strings bukan hanya hiasan status bar — ia adalah bahasa untuk meminta informasi dari tmux. display-message -p mencetak hasil ekspansi format ke stdout, sehingga kalian bisa menginterogasi kondisi nyata:

tmux info
tmux show -g | head
tail -n 50 "$HOME/.tmux-$(id -u).log"

tmux display-message -p '#{session_name}:#{window_name}.#{pane_index}'
tmux display-message -p '#{pane_current_path}'
tmux display-message -p '#{pane_width}x#{pane_height}'
tmux display-message -p '#{client_termname}'

Contoh paling praktis: tmux display-message -p '#{client_termname}' memberi tahu TERM yang dilihat client — pembanding pertama saat warna terlihat salah. Dan #{pane_current_path} menjawab "sebenarnya saya sedang di direktori mana" — penyebab umum command yang tidak berjalan seperti dugaan.

Tip

Pola debugging yang kuat: bangun status bar dari format yang sama dengan yang sedang kalian uji. Jika #{pane_current_path} mencetak nilai aneh di display-message -p, maka status bar yang memakai format yang sama juga akan salah — jadi masalahnya ada di format atau di kondisi sistem, bukan di tmux.

#Masalah Status Bar, Warna, dan TERM

#TERM yang Tidak Konsisten

Terminal menentukan seberapa banyak kemampuan yang diiklankan: warna, mouse, clear, dan lainnya. TERM yang tidak dikenali atau terlalu rendah membuat tmux menolak berjalan atau merender dengan buruk.

Bandingkan TERM di dalam dan luar tmux

echo $TERM
tmux display-message -p '#{client_termname}'
tput colors

Jika di dalam tmux TERM bukan tmux-256color atau sejenisnya, aplikasi tidak akan memakai kemampuan penuh. Perbaiki dengan set -g default-terminal "tmux-256color" di ~/.tmux.conf, lalu restart server (bukan sekadar reload config). TERM hanya dibaca saat client/server dimulai — mengubah config lalu reload saja tidak cukup.

#Warna yang Salah

Warna kusam biasanya berarti salah satu tautan dalam rantai warna — aplikasi → tmux → terminal — menyatakan kemampuan yang lebih rendah dari kenyataan:

Kondisi	Diagnosis
Warna 256 hilang di dalam tmux	`default-terminal` bukan `tmux-256color`
True color hilang	Fitur RGB tidak diiklankan: `set -g terminal-features 'xterm*:RGB'`
Warna beda di dalam vs luar tmux	`TERM` luar lebih kaya daripada yang dilihat tmux

#Debugging Keybinding yang Konflik

#Menelusuri list-keys

Gejala klasik: "saya bind C-a, tapi tidak jalan." Penyebab umum: binding tertimpa oleh baris lain, atau tombol sudah dipakai di key table yang berbeda. Tmux menampilkan semua binding dengan list-keys:

Cari binding yang konflik

tmux list-keys -T prefix | grep C-a
tmux list-keys -n | grep C-a
tmux list-keys -T prefix | grep send-prefix

-T prefix menelusuri tabel prefix (tabel default), -n tabel root (binding tanpa prefix). Ketika satu key tampil dua kali, binding terakhir yang dimuatlah yang menang — temukan di bagian mana config menimpa, dan ubah salah satunya.

#Reproduksi Minimal dengan tmux -f /dev/null

Men-debug konfigurasi yang panjang itu sulit karena banyak variabel sekaligus. Trik standar: jalankan tmux tanpa config apa pun sebagai baseline, lalu tambahkan baris demi baris sampai masalah muncul:

Mulai tmux murni tanpa config

tmux -f /dev/null new -s debug
tmux -f /dev/null source-file ~/.tmux.conf

Di session debug, kalian tahu persis bahwa masalah tidak berasal dari konfigurasi pengguna. Lalu jalankan tmux source-file ~/.tmux.conf satu file (atau satu blok) pada satu waktu — ketika gejala muncul, baris terakhir yang dimuat adalah tersangka utamanya. Ini adalah bisection sederhana yang bekerja di konfigurasi sebesar apa pun.

Warning

source-file tidak menghapus efek baris sebelumnya — ia hanya menumpuk perintah di atas kondisi yang ada. Jika kalian menguji dengan source-file, mulai dari kondisi bersih: jalankan tmux -f /dev/null new -s debug dulu, baru source-file. Kalau tidak, hasilnya akan menyesatkan.

#Masalah Layout dan Pane

Layout yang "tidak sesuai" hampir selalu karena window lebih besar dari yang tmux duga — misalnya setelah resize terminal atau attach dari layar yang lebih kecil. Tmux menyimpan beberapa layout dalam history per window:

Kembalikan layout

tmux select-layout -t myname:0 even-horizontal
tmux next-layout -t myname:0
tmux resize-pane -R 5

next-layout (default Prefix + Space) mengiterasi layout preset; select-layout menerapkan layout spesifik secara eksplisit. Jika pane tidak bisa di-resize, periksa set -g mouse on (resize lewat drag border) dan aggressive-resize yang mengubah perilaku ukuran pada window dengan banyak client.

#Tabel Error Umum dan Solusinya

Gejala	Kemungkinan Penyebab	Solusi
`open terminal failed: unknown`	`TERM` tidak dikenali terminal	Set `TERM` yang valid (`xterm-256color`) sebelum tmux
Status bar kosong	`status` off atau format kosong	`tmux show -g status` dan `show -g status-left`
Warna kusam, 256 tidak jalan	`default-terminal` bukan 256	`set -g default-terminal "tmux-256color"`, restart server
Keybinding tidak berefek	Binding tertimpa di config	`tmux list-keys -T prefix` untuk menelusuri
Server keluar mendadak	Crash atau socket rusak	Cek `~/.tmux-<uid>.log` dan `tmux info`, lalu `kill-server`
Session "hilang" padahal ada	Socket path berbeda	Gunakan `-L`/`-S` yang sama persis dengan saat membuatnya
Layout tidak sesuai window	Window lebih besar dari layar awal	`select-layout` atau `Prefix + Space` untuk next layout

#Kesalahan Umum (Common Pitfalls)

Langsung menghapus config sebelum mengecek TERM. Banyak "tmux rusak" ternyata hanya TERM yang tidak dikenali terminal. Cek echo $TERM dan tput colors dulu.
Mengabaikan log server. ~/.tmux-<uid>.log dan show-messages memuat pesan error yang persis — termasuk baris config yang gagal. Baca sebelum menebak.
Men-debug config panjang tanpa baseline. Selalu mulai dari tmux -f /dev/null lalu tambahkan baris satu per satu. Menebak di config 300 baris adalah cara tercepat membuang waktu.
Lupa bahwa config hanya dimuat saat server start. Mengubah ~/.tmux.conf lalu hanya reload tidak cukup untuk option yang dibaca saat startup seperti default-terminal dan escape-time. Restart server.
Mengira session hilang padahal socket berbeda. tmux ls tanpa -L hanya melihat socket default. Jika biasa memakai -L work, periksa dengan tmux -L work ls.
Menjalankan kill-server tanpa memeriksa. kill-server mematikan semua session semua pengguna socket itu. Periksa tmux ls dulu, dan pertimbangkan kill-session yang lebih spesifik.

#Penutup

Episode ini memberi kalian metode untuk menghadapi tmux yang tidak berperilaku: bertanya pada tmux itu sendiri dengan list-sessions, list-clients, list-panes, tmux info, dan display-message -p; membaca log server dan show-messages; mendiagnosis masalah status bar, warna, dan TERM; menelusuri konflik keybinding dengan list-keys; mereproduksi masalah pada tmux -f /dev/null; serta memperbaiki layout yang tidak sesuai. Tabel error umum menjadi peta cepat yang bisa kalian gunakan saat gejala muncul lagi.

Poin yang harus kalian bawa pulang:

Diagnosis dimulai dari data, bukan tebakan — tmux selalu bisa diintrospeksi.
display-message -p mengubah format menjadi jawaban.
Baseline -f /dev/null memisahkan masalah config dari masalah lingkungan.
TERM dan versi socket adalah dua tersangka pertama yang harus disingkirkan.

Di episode 24 selanjutnya kita akan membahas performance & resource optimization — bagaimana membuat tmux ringan, cepat dimulai, dan hemat memory di mesin dengan resource terbatas. Setelah tahu cara memperbaiki yang rusak, kita akan belajar mencegah yang tidak perlu. Sampai jumpa di episode 24!