Common Errors and Fixes
This reference covers the most frequently encountered VisiData issues, their root causes, and the fastest fixes.
Recognize the error category first (display, encoding, type, or loading), then apply the corresponding fix. Most issues are environment or data quality problems, not VisiData bugs.
Display Issues
Garbled Unicode / Braille Characters
Symptom: Graph canvas shows ? or boxes instead of Braille dots.
Cause: Terminal does not support UTF-8.
# Fix:
export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8
# Add to ~/.bashrc for persistence
echo 'export LANG=en_US.UTF-8' >> ~/.bashrc
echo 'export LC_ALL=en_US.UTF-8' >> ~/.bashrc
Missing Colors / Monochrome Display
Symptom: Everything looks the same color; no highlighting.
Cause: TERM not set to a 256-color terminal type.
# Fix:
export TERM=xterm-256color
echo 'export TERM=xterm-256color' >> ~/.bashrc
Screen Not Refreshing Properly
Symptom: Ghost text, incomplete redraws.
Fix inside VisiData:
Ctrl+L # force full screen redraw
Encoding Errors
UnicodeDecodeError When Opening a File
Symptom: VisiData shows an error traceback when opening a file.
Cause: File is not UTF-8 (e.g., Latin-1, CP1252).
# Detect encoding first
file /var/www/html/exports/data.csv
chardet /var/www/html/exports/data.csv # requires: pip install chardet
# Open with correct encoding
vd --encoding latin1 data.csv
vd --encoding cp1252 data.csv
In .visidatarc for persistent default:
options.encoding = 'latin1'
Type Errors
#ERR in a Column Cell
Symptom: A cell shows #ERR after type casting.
Cause: The cell value cannot be converted to the target type (e.g., "N/A" cast to # int).
Fix: Clean the bad values first:
# Select rows with #ERR (they show as error)
z|
# Enter: value == None (or check the actual bad values)
# Either delete bad rows or fix values
ge
# Enter: 0
# Then re-apply the type cast
NameError in a Python Expression
Symptom: Expression column (=) shows NameError: name 'col_name' is not defined.
Cause: Column name has spaces or special characters.
# Instead of:
= first name + ' ' + last name # FAILS — space in name
# Use dict-style access:
= row['first name'] + ' ' + row['last name'] # WORKS
Sort Order Wrong for Numbers
Symptom: Numbers sort as: 1, 10, 100, 2, 20.
Cause: Column type is string — lexicographic sort.
# Fix: cast the column to integer
# (on the column)
# Then sort again
[ or ]
Loading Failures
vd: command not found
# Fix 1: Add pip user install to PATH
export PATH="$HOME/.local/bin:$PATH"
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
# Fix 2: Run via Python explicitly
python3 -m visidata file.csv
ModuleNotFoundError for a Format
Symptom: ModuleNotFoundError: No module named 'openpyxl'
# Install the missing dependency
pip install openpyxl # Excel
pip install pyarrow # Parquet
pip install requests # URL loading
pip install psycopg2-binary # PostgreSQL
# Or install all extras
pip install "visidata[full]"
File Opens as Single Long Text Column
Cause: Wrong delimiter detected.
# Fix: specify delimiter explicitly
vd -f csv --csv-delimiter ';' data.csv
vd -f tsv data.tsv
vd -f fixed report.txt
Sheet / Navigation Issues
Cannot Return to Source Sheet
Symptom: Pressing q exits VisiData instead of going back.
Cause: You are on the last remaining sheet in the stack.
# Check the sheet stack first
Shift+S # shows all sheets
# Navigate to desired sheet with Enter
All Edits Lost After ^R (Reload)
Cause: Ctrl+R reloads the sheet from disk — all in-memory changes are discarded.
# Save before reloading
Ctrl+S
# Enable undo for recovery
options.undo = True # in ~/.visidatarc
Performance Issues
VisiData Slow on Large Files
# Limit rows during exploration
vd --max-rows 100000 large_file.csv
# Use lazy loading for subsheets
options.load_lazy = True # in ~/.visidatarc
# Avoid derived columns on very large sheets — they compute on-demand per row
Frequency Table Slow
Cause: Very many distinct values in the column.
# Use a filtered/sampled sheet first
# Select a subset with |, open with "
# Then run Shift+F on the smaller sheet
Troubleshooting Checklist
| Category | First Check | Command |
|---|---|---|
| Display | Is TERM set? | echo $TERM |
| Encoding | Is LANG UTF-8? | echo $LANG |
| Format | Is the delimiter right? | Open with -f csv --csv-delimiter ',' |
| Type | Is the column typed? | Check header row for type indicator |
| Performance | Is max-rows set? | Add --max-rows 100000 |
| Error traceback | View full error | Ctrl+E inside VisiData |
Viewing Error Tracebacks
Ctrl+E # view traceback for the most recent error
g Ctrl+E # view tracebacks for all recent errors
z Ctrl+E # view traceback for error in current cell
Hands-On Practice
# Simulate a common error:
echo "name,amount\nAlice,N/A\nBob,50" > /tmp/bad.csv
vd /tmp/bad.csv
# 1. Move to 'amount' column, press # → see #ERR on Alice row
# 2. Press Ctrl+E to view error detail
# 3. Move to Alice's amount cell, press e → change to 0 → Enter
# 4. Press # again → no more #ERR
# 5. Press Ctrl+S → save fixed file