Skip to main content

Troubleshooting

This guide helps diagnose and resolve common issues with television.

Installation Issues​

Command Not Found​

If tv isn't recognized after installation:

  1. Check PATH: Ensure the installation directory is in your PATH
  2. New shell session: Open a new terminal or run source ~/.bashrc (or equivalent)
  3. Verify installation: which tv or where tv (Windows)

Permission Denied​

chmod +x /path/to/tv  # Linux/macOS

Cargo Install Fails​

# Update Rust
rustup update

# Try with --locked flag
cargo install --locked television

Display Issues​

Colors Look Wrong​

  1. Check terminal support: Ensure your terminal supports 256 colors or truecolor
  2. TERM variable: Try export TERM=xterm-256color
  3. Theme mismatch: Some themes assume dark/light background
[ui]
theme = "default"  # Try different themes

Characters Not Rendering​

Ensure your terminal font supports the characters tv uses. Try a Nerd Font or similar.

UI Garbled or Misaligned​

  1. Terminal resize: Try resizing your terminal
  2. Clear screen: Press Ctrl+L or restart tv
  3. Alternate screen: Some terminals don't support alternate screen properly
# Force redraw
tv files  # Then Ctrl+L

Preview Not Showing​

  1. No preview configured: Some channels don't have previews
  2. Preview command missing: Install required tools (bat, cat, etc.)
  3. Preview hidden: Press Ctrl+O to toggle
  4. Preview disabled: Check for --no-preview or hidden = true in config

Channel Issues​

Channel Not Found​

# List available channels
tv list-channels

# Update community channels
tv update-channels

Source Command Fails​

Test the source command directly:

# If channel uses: fd -t f
fd -t f  # Run it directly to see errors

Common causes:

  • Missing required tool (check requirements in channel)
  • Wrong working directory
  • Permission issues

No Results Showing​

  1. Empty source: Source command returns nothing
  2. Filter too restrictive: Clear your input
  3. Wrong directory: Check working directory
# Start in specific directory
tv files /path/to/search

Preview Command Fails​

Test preview command manually:

# If preview uses: bat -n --color=always '{}'
bat -n --color=always "test_file.txt"

Configuration Issues​

Config Not Loading​

Check config location:

# Linux/macOS
ls -la ~/.config/television/config.toml

# Or with custom location
echo $TELEVISION_CONFIG

Config Syntax Error​

Validate TOML syntax:

# Install a TOML validator
pip install toml-cli
toml-cli validate ~/.config/television/config.toml

Common TOML errors:

  • Missing quotes around strings with special characters
  • Unclosed brackets
  • Invalid escape sequences

Keybindings Not Working​

  1. Check binding syntax: Use lowercase (ctrl-a, not Ctrl-A)
  2. Conflicts: Channel keybindings override global ones
  3. Terminal intercepts: Some terminals capture certain key combinations

Test a simple binding:

[keybindings]
f1 = "toggle_help"  # F1 is rarely intercepted

Shell Integration Issues​

Ctrl+T / Ctrl+R Not Working​

  1. Init not sourced: Ensure eval "$(tv init zsh)" is in your shell config
  2. Reload shell: source ~/.zshrc or open new terminal
  3. Key conflict: Another tool might be using these keys
# Check if tv init generates output
tv init zsh

Wrong Channel Selected​

Adjust channel triggers in config:

[shell_integration.channel_triggers]
"files" = ["cat", "vim", "code"]
"dirs" = ["cd", "ls"]

Performance Issues​

Slow Startup​

  1. Source command slow: Test the source command independently

Memory Usage​

  1. Limit source output: try piping into head -n N in source command. Start with N=100.
  2. Disable caching: --no-cache-preview

Logs​

Tv writes logs to help diagnose issues:

PlatformLocation
Linux~/.local/share/television/television.log
macOS~/Library/Application Support/television/television.log
Windows%LocalAppData%\television\television.log

Or if $TELEVISION_DATA is set: $TELEVISION_DATA/television.log

To see logs during development:

tail -f ~/.local/share/television/television.log

Debug Mode​

Run tv in debug mode for more information:

RUST_LOG=debug tv files

And check the logs.

Getting Help​

If you can't resolve an issue:

  1. Check GitHub Issues: television issues
  2. Discord: Join the community Discord
  3. Create an issue: Include:
    • tv version (tv --version)
    • OS and terminal
    • Steps to reproduce
    • Relevant config/channel files
    • Log output

Reset to Defaults​

If all else fails, start fresh:

# Backup and remove config
mv ~/.config/television ~/.config/television.bak

# Run tv - which creates new default config
tv files