Skip to main content
This page covers common problems you might encounter when running bofa and how to resolve them.

​
No Animation (Plain Text Only)

​
TERM=dumb

Symptom: bofa prints plain text instead of showing animations Cause: Terminal type is set to dumb, which indicates no advanced capabilities Source: __init__.py:124-126 
if os.environ.get("TERM", "").lower() == "dumb":
    print(msg)
    return
Solution: Set a proper terminal type: 
export TERM=xterm-256color
bofa

​
Non-Interactive Terminal

Symptom: bofa prints plain text when run in pipes or redirects Cause: Output is not connected to a TTY (terminal) Source: __init__.py:124 
if not sys.stdout.isatty():
    print(msg)
    return
Examples of non-interactive contexts:
  • Piping output: bofa | less
  • Redirecting to file: bofa > output.txt
  • Running in CI/CD environments
  • Inside certain IDE terminals
Solution: Run bofa directly in an interactive terminal, or use the plain text output in non-interactive contexts (this is expected behavior).

​
Unicode Display Issues

​
Garbled Characters

Symptom: Special characters display as ?, boxes, or garbled text Cause: Terminal encoding doesn’t support Unicode Source: __init__.py:49-57 bofa tests if the terminal can encode Unicode characters: 
def _unicode_ok() -> bool:
    encoding = sys.stdout.encoding
    if not encoding:
        return False
    try:
        "✦❖✺".encode(encoding)
    except UnicodeEncodeError:
        return False
    return True
Automatic Fallback: bofa automatically falls back to ASCII characters if Unicode encoding fails. Solution: If you want full Unicode effects: 
# Check current encoding
echo $LANG

# Set UTF-8 encoding (Linux/macOS)
export LANG=en_US.UTF-8
export LC_ALL=en_US.UTF-8

# Verify encoding
python3 -c "import sys; print(sys.stdout.encoding)"
Expected Output: Should show UTF-8 or utf-8

​
Font Missing Glyphs

Symptom: Some Unicode characters render as empty boxes even with UTF-8 encoding Cause: Terminal font doesn’t include the required Unicode glyphs Characters Used:
  • Confetti: ✦✧❖✺✹✷✸✶✱✲✳✴✵✼✽❇❈❉❊
  • Fireworks: ✦✧❇❈✺
Solution: Install a font with comprehensive Unicode support:
  • macOS: SF Mono, Menlo (built-in)
  • Linux: Noto Sans Mono, DejaVu Sans Mono, FiraCode
  • Windows: Cascadia Code, Consolas

​
Terminal Size Issues

​
Text Appears Cramped

Symptom: Text and effects don’t fit properly in the terminal Cause: Terminal window is too narrow Source: __init__.py:309-314 bofa requires a minimum width: 
columns = shutil.get_terminal_size(fallback=(80, 24)).columns
target = columns - 2
return max(34, min(target, 120))  # Min: 34, Max: 120
Minimum Requirements:
  • Width: 34 characters (36 recommended for comfort)
  • Height: No strict minimum, but 24+ lines recommended
Solution: Resize your terminal window to at least 80×24 characters.

​
Size Detection Fails

Symptom: Effects don’t adapt to your terminal size Cause: Terminal size cannot be detected Source: __init__.py:310 Fallback size is 80×24 if detection fails. Solution: Ensure you’re running in a standard terminal emulator that supports size queries (most modern terminals do).

​
Performance Issues

​
Animations Lag or Stutter

Symptom: Effects play slowly or skip frames Possible Causes:
  1. Slow Terminal Emulator: Some terminals can’t render at 90 fps
  2. SSH Connection: Network latency affects animation smoothness
  3. Large Terminal: Very large terminal windows (>120 columns) require more rendering
Frame Rate: __init__.py:102 
terminal_config.frame_rate = 90  # 90 fps
Solutions:
  • Use a hardware-accelerated terminal (Alacritty, Kitty, WezTerm)
  • Run bofa locally rather than over SSH
  • Reduce terminal window size
  • Close other resource-intensive applications

​
High CPU Usage

Symptom: bofa consumes significant CPU while running Cause: Rendering animations at 90 fps is CPU-intensive Expected Behavior: This is normal. CPU usage should drop to zero after animations complete.

​
Interrupt Handling

​
Stuck in Animation

Symptom: Need to exit bofa during an animation Solution: Press Ctrl+C (keyboard interrupt) Source: __init__.py:153-155, 184-186 bofa handles interrupts gracefully: 
try:
    _play_intro(...)
    _play_interlude(...)
except KeyboardInterrupt:
    print(msg)  # Prints plain text
    return
Behavior: Immediately exits and prints the plain text message.

​
Dependency Issues

​
Module Not Found: terminaltexteffects

Symptom: Error when running bofa after installation 
ModuleNotFoundError: No module named 'terminaltexteffects'
Cause: terminaltexteffects dependency not installed Solution: Reinstall bofa to ensure dependencies are installed: 
pip install --upgrade bofa
Version Requirement: pyproject.toml:11 
dependencies = [
    "terminaltexteffects>=0.14.2",
]

​
Python Version Too Old

Symptom: Syntax errors or import errors when running bofa Cause: Python version is below 3.10 Source: pyproject.toml:9 
requires-python = ">=3.10"
Solution: Upgrade to Python 3.10 or higher: 
# Check current version
python3 --version

# Install Python 3.10+ using your system package manager
# Ubuntu/Debian:
sudo apt install python3.11

# macOS with Homebrew:
brew install [email protected]

​
Color Issues

​
Colors Look Wrong or Washed Out

Symptom: Rainbow colors don’t display correctly Possible Causes:
  1. Limited Color Support: Terminal doesn’t support true color (24-bit)
  2. Terminal Color Scheme: Theme overrides colors
Colors Used: __init__.py:38-46 
RAINBOW_STOPS = (
    Color("#e81416"),  # Red
    Color("#ffa500"),  # Orange
    Color("#faeb36"),  # Yellow
    Color("#79c314"),  # Green
    Color("#487de7"),  # Blue
    Color("#4b369d"),  # Indigo
    Color("#70369d"),  # Violet
)
Solutions:
  1. Enable True Color: Ensure your terminal supports 24-bit color
# Test true color support
curl -s https://raw.githubusercontent.com/JohnMorales/dotfiles/master/colors/24-bit-color.sh | bash
  1. Check TERM Variable:
echo $TERM
# Should be something like: xterm-256color, screen-256color, etc.
  1. Use a Modern Terminal:
    • Recommended: Alacritty, Kitty, WezTerm, iTerm2 (macOS)
    • Avoid: Very old terminal emulators that only support 16 colors

​
Moon Mode Issues

​
Moon Appears Distorted

Symptom: Circle looks oval or stretched when using bofa --moon Cause: Character aspect ratio doesn’t match your terminal font Source: moon.py:9 
CHAR_ASPECT = 2.0  # Characters are 2x taller than wide
Solution: This is expected with some fonts. The 2.0 ratio works for most monospace fonts, but some fonts have different proportions. This is cosmetic and doesn’t affect functionality.

​
Moon Too Small

Symptom: Moon doesn’t fill much of the screen Cause: Moon size is limited to prevent distortion Source: moon.py:15 
R = min(rows // 2 - 1, 10)  # Max radius: 10 rows
Limitation: Maximum radius is capped at 10 rows to ensure proper circular appearance. Solution: This is by design. The moon maintains proper proportions at this size.

​
Still Having Issues?

If you encounter a problem not covered here:
  1. Check Python Version: Must be 3.10 or higher
  2. Verify Terminal: Run in a modern terminal emulator with UTF-8 support
  3. Test Encoding: Run python3 -c "import sys; print(sys.stdout.encoding)"
  4. Review Error Messages: Python tracebacks often indicate the specific issue
  5. Try Plain Text Mode: Set TERM=dumb to verify basic functionality
GitHub Issues: Report bugs at the bofa repository with:
  • Python version (python3 --version)
  • Terminal type (echo $TERM)
  • Encoding (python3 -c "import sys; print(sys.stdout.encoding)")
  • Error message or unexpected behavior description

Build docs developers (and LLMs) love

Get started for freeTalk to us