Skip to main content
This guide covers common problems you might encounter while using Pomo and how to resolve them.

​
Debug logging

Before troubleshooting, enable debug logging to see detailed execution information: 
DEBUG=1 pomo 25m
This creates a debug.log file in the current directory with detailed logs (see cmd/root.go:58-68).
Debug logs include config loading, notification attempts, command execution, and database operations. Always check this file first when diagnosing issues.

​
Configuration issues

Problem: Pomo doesn’t load your custom configuration.Solution: Pomo searches for config files in this order (see config/config.go:166-184):
  1. Current directory: ./pomo.yaml (highest priority)
  2. System config directory:
    • Linux/macOS: ~/.config/pomo/pomo.yaml
    • Windows: %APPDATA%\pomo\pomo.yaml
  3. Built-in defaults if no config found
Check which config is loaded:
DEBUG=1 pomo 25m 2>&1 | grep "config"
Create config in the correct location:
# Linux/macOS
mkdir -p ~/.config/pomo
touch ~/.config/pomo/pomo.yaml

# Or use current directory
touch pomo.yaml
Problem: Config file exists but Pomo shows errors or uses defaults.Common YAML syntax errors:
# ❌ Wrong - incorrect indentation
work:
duration: 25m

# ✅ Correct - proper indentation
work:
  duration: 25m

# ❌ Wrong - missing quotes for special characters
notification:
  title: It's time!

# ✅ Correct - quoted strings with special chars
notification:
  title: "It's time!"

# ❌ Wrong - wrong array syntax for commands
then: [paplay ~/sounds/bell.wav]

# ✅ Correct - nested array syntax
then:
  - [paplay, ~/sounds/bell.wav]
Validate your YAML:
# Use yamllint if available
yamllint ~/.config/pomo/pomo.yaml
Problem: Error message like “invalid duration: ‘abc’”Solution: Use proper Go duration format:
  • Valid: 25m, 1h30m, 90m, 5m30s
  • Invalid: 25, 1:30, 90 minutes
work:
  duration: 25m  # ✅ Correct
  # duration: 25  # ❌ Wrong - missing unit
The duration parsing happens in cmd/runner.go:42-46.

​
Notification issues

Problem: No desktop notifications when sessions complete.Platform-specific solutions:Linux:
  • Check if notification daemon is running: 
    ps aux | grep notification
  • Install notification support: 
    # Debian/Ubuntu
sudo apt-get install libnotify-bin

# Fedora/RHEL
sudo dnf install libnotify
  • Test notifications manually: 
    notify-send "Test" "Hello"
macOS:
  • Grant terminal notification permissions:
    1. System Preferences → Notifications
    2. Find your terminal app (Terminal, iTerm2, etc.)
    3. Enable “Allow Notifications”
Windows:
  • Check Windows notification settings:
    1. Settings → System → Notifications
    2. Ensure notifications are enabled
    3. Check if app notifications are allowed
Verify config:
work:
  notification:
    enabled: true  # Must be true
    title: work finished 🎉
    message: time to take a break
Problem: Logs show “failed to send notification: permission denied”Solution:
  1. macOS: Grant permission in System Preferences → Notifications
  2. Linux (Flatpak): Grant notification permission: 
    flatpak permission-set notifications app-id yes
  3. Snap packages: Ensure notification interface is connected: 
    snap connections pomo
Problem: Custom icon path doesn’t display.Solution:
work:
  notification:
    # ✅ Use absolute path or ~/
    icon: ~/icons/pomo.png
    
    # ❌ Avoid relative paths
    # icon: ./icon.png
  • Ensure the file exists: ls -l ~/icons/pomo.png
  • Use PNG format for best compatibility
  • Path expansion happens in config/config.go:129-135

​
Display issues

Problem: Timer shows garbled characters or boxes.Solution:
  1. Use a terminal with proper Unicode support:
    • ✅ Modern terminals: iTerm2, Alacritty, Windows Terminal
    • ⚠️ May have issues: older cmd.exe, basic terminal emulators
  2. Try different fonts: 
    asciiArt:
  enabled: true
  font: mono12  # Try: mono12, rebel, ansi, ansiShadow
    Available fonts are defined in ui/ascii/fonts.go.
  3. Disable ASCII art if problems persist: 
    asciiArt:
  enabled: false
Problem: Timer displays in monochrome.Solution:
  1. Check terminal color support: 
    echo $TERM
# Should show: xterm-256color, screen-256color, etc.
  2. Enable colors in terminal: 
    # Bash/Zsh
export TERM=xterm-256color
  3. Verify color in config: 
    asciiArt:
  color: "#5A56E0"  # Hex color
  # color: "none"    # Disable color
Problem: pomo stats shows boxes instead of icons in heatmap.Solution:The heatmap requires a Nerd Font to display icons correctly.
  1. Install a Nerd Font: 
    # macOS with Homebrew
brew tap homebrew/cask-fonts
brew install font-hack-nerd-font
  2. Configure your terminal to use the font:
    • iTerm2: Preferences → Profiles → Text → Font
    • Alacritty: Edit ~/.config/alacritty/alacritty.yml
    • Windows Terminal: Settings → Profiles → Appearance → Font face
  3. Choose a Nerd Font variant:
    • FiraCode Nerd Font
    • Hack Nerd Font
    • JetBrainsMono Nerd Font

​
Sound and command issues

Problem: No sound when using then commands.Solution:
  1. Verify audio player is installed: 
    # Linux
which paplay

# macOS
which afplay
  2. Test command manually: 
    paplay ~/sounds/bell.wav
  3. Check file path and format:
    • Use absolute paths: ~/sounds/bell.wav
    • Verify file exists: ls -l ~/sounds/bell.wav
    • Use supported formats: WAV, MP3, OGG
  4. Check command syntax: 
    # ✅ Correct
then:
  - [paplay, ~/sounds/bell.wav]

# ❌ Wrong - missing array wrapper
then: [paplay, ~/sounds/bell.wav]
See Sound notifications for detailed setup.
Problem: Commands in then field don’t execute.Solution:
  1. Enable debug logging: 
    DEBUG=1 pomo 25m
    Check debug.log for errors like: 
    failed to run command: exec: "invalid-cmd": executable file not found
  2. Verify command exists: 
    which your-command
  3. Use full paths for safety: 
    then:
  - [/usr/bin/notify-send, "Pomo", "Done"]
  4. Check timeout (5 seconds): Commands exceeding 5 seconds are terminated (see actions/actions.go:15). For long tasks, run in background: 
    then:
  - [sh, -c, "nohup ~/long-script.sh &"]
See Custom commands for advanced usage.

​
Database and statistics issues

Problem: pomo stats displays empty or zero data.Cause:
  • No completed sessions recorded yet
  • Database file missing or corrupted
  • Database location changed
Solution:
  1. Complete at least one full session (don’t quit early)
  2. Check database location:
    • Linux/macOS: ~/.local/state/pomo/pomo.db
    • Windows: %APPDATA%\pomo\pomo.db Defined in db/connect.go:71-92.
  3. Verify database exists: 
    # Linux/macOS
ls -l ~/.local/state/pomo/pomo.db

# Check database integrity
sqlite3 ~/.local/state/pomo/pomo.db "SELECT COUNT(*) FROM sessions;"
Problem: Errors like “failed to connect to the db” in logs.Solution:
  1. Check directory permissions: 
    # Linux/macOS
ls -ld ~/.local/state/pomo
chmod 755 ~/.local/state/pomo
  2. Ensure SQLite is available: Pomo uses embedded SQLite (modernc.org/sqlite), but the directory must be writable.
  3. Remove corrupted database: 
    # Backup first!
cp ~/.local/state/pomo/pomo.db ~/pomo-backup.db

# Remove corrupted DB (will recreate on next run)
rm ~/.local/state/pomo/pomo.db
Problem: Completed sessions don’t appear in pomo stats.Solution:
  1. Ensure you complete the full session Quitting early (Ctrl+C before timer ends) may not record stats.
  2. Check for database write errors: 
    DEBUG=1 pomo 1m
# Complete the session, then check debug.log
grep -i "db\|database\|insert" debug.log
  3. Verify database is writable: 
    # Linux/macOS
ls -l ~/.local/state/pomo/pomo.db
# Should NOT be owned by root or read-only

​
Installation issues

Problem: pomo: command not found after installing.Solution by installation method:Go install:
# Ensure Go bin is in PATH
export PATH=$PATH:$(go env GOPATH)/bin

# Add to ~/.bashrc or ~/.zshrc
echo 'export PATH=$PATH:$(go env GOPATH)/bin' >> ~/.bashrc
Homebrew (macOS):
# Verify installation
brew list pomo

# Reinstall if needed
brew reinstall bahaaio/pomo/pomo
From source:
# Move binary to PATH
sudo mv pomo /usr/local/bin/

​
Getting help

If your issue isn’t covered here:
  1. Enable debug logging and check debug.log: 
    DEBUG=1 pomo 25m
cat debug.log
  2. Check existing issues on GitHub
  3. Create a new issue with:
    • Your operating system and version
    • Pomo version: pomo --version
    • Config file contents (remove sensitive data)
    • Relevant debug.log excerpts
    • Steps to reproduce the problem

Build docs developers (and LLMs) love

Get started for freeTalk to us