Troubleshooting

Troubleshooting

Common issues and solutions.

---

Startup Issues

TaskFlow Won't Start

Symptoms: Nothing happens or immediate exit.

Solutions:

1. Run with verbose output:

   taskflow -vvv

2. Check terminal type:

   echo $TERM
   # Should be xterm-256color or similar

3. Set terminal explicitly:

   TERM=xterm-256color taskflow

4. Check for config errors:

   taskflow --no-config

"Permission Denied" Error

Solutions:

1. Check data directory permissions:

   ls -la ~/.local/share/taskflow/

2. Create directory if missing:

   mkdir -p ~/.local/share/taskflow/

3. Fix permissions:

   chmod 755 ~/.local/share/taskflow/

"Config Parse Error"

Solutions:

1. Check TOML syntax:

   cat ~/.config/taskflow/config.toml

2. Look for common errors:

   • Missing quotes around strings
   • Incorrect indentation
   • Invalid section names

3. Reset config:

   rm ~/.config/taskflow/config.toml
   taskflow  # Creates fresh config

---

Display Issues

Colors Look Wrong

Solutions:

1. Check color support:

   echo $COLORTERM
   # Should be "truecolor" or "24bit"

2. Enable true color:

   export COLORTERM=truecolor

3. Use basic colors in theme:

   [theme]
   header_bg = "blue"  # Instead of "#1e1e2e"

4. Check terminal settings for color scheme.

No Colors at All

Solutions:

1. Set TERM:

   export TERM=xterm-256color

2. Check NO_COLOR isn't set:

   unset NO_COLOR

3. Verify terminal supports colors:

   tput colors  # Should show 256 or higher

Display Garbled / Characters Wrong

Solutions:

1. Check locale:

   echo $LANG
   # Should be UTF-8, e.g., en_US.UTF-8

2. Set UTF-8:

   export LANG=en_US.UTF-8
   export LC_ALL=en_US.UTF-8

3. Check terminal font supports Unicode.

Screen Flickers

Solutions:

1. Disable animations:

   [ui]
   animation_speed = 0

2. Try different terminal emulator.

3. Update terminal to latest version.

---

Data Issues

Tasks Disappeared

Possible Causes:

1. Different data directory - Check --data-dir or config
2. Different backend - Check --backend or config
3. File permissions - Check read access

Solutions:

1. Find your data:

   find ~/.local/share -name "tasks.*" 2>/dev/null
   find ~ -name "taskflow" -type d 2>/dev/null

2. Check which file TaskFlow is using:

   taskflow -v  # Shows data location

3. Restore from backup if available.

Can't Save Data

Solutions:

1. Check disk space:

   df -h ~/.local/share/

2. Check directory is writable:

   touch ~/.local/share/taskflow/test
   rm ~/.local/share/taskflow/test

3. Check for filesystem errors.

Data Corrupted

Solutions:

1. Restore from backup.

2. For JSON/YAML, try to fix manually:

   # Validate JSON
   python -m json.tool ~/.local/share/taskflow/tasks.json

3. For SQLite:

   sqlite3 ~/.local/share/taskflow/tasks.db "PRAGMA integrity_check;"

4. Export what you can and start fresh.

---

Performance Issues

Slow Startup

Solutions:

1. Use SQLite for large datasets:

   [storage]
   backend = "sqlite"

2. Archive old completed tasks.

3. Check for large time log entries.

High Memory Usage

Solutions:

1. Use SQLite backend (loads on-demand).

2. Archive old data:

   taskflow --export archive.csv --filter "completed_before:2024-01-01"

Laggy UI

Solutions:

1. Disable animations:

   [ui]
   animation_speed = 0

2. Switch to SQLite backend.

3. Check terminal performance (try different emulator).

---

Keybinding Issues

Keys Don't Work

Solutions:

1. Check for conflicts:

   • Terminal shortcuts
   • tmux/screen bindings
   • Desktop environment shortcuts

2. Test in raw terminal:

   # Exit tmux/screen first
   taskflow

3. Check keybindings config:

   grep -A50 "\[keybindings\]" ~/.config/taskflow/config.toml

Function Keys Don't Work

Solutions:

1. Terminal may intercept F-keys. Check terminal settings.

2. In tmux, you may need:

   set -g xterm-keys on
   

3. Try alternate bindings in config.

Ctrl+Key Combinations Fail

Solutions:

1. Check terminal sends correct sequences.

2. Some combinations reserved:

   • Ctrl+C (interrupt)
   • Ctrl+Z (suspend)
   • Ctrl+S (flow control)

3. Disable flow control:

   stty -ixon

---

Timer Issues

Timer Shows Wrong Time

Solutions:

1. Check system time:

   date

2. Check timezone:

   echo $TZ

3. Edit time log to fix: Press L, navigate, press e.

Timer Lost After Restart

Shouldn't happen - timer persists. But if it does:

1. Check same data directory is used.

2. Check file wasn't corrupted.

3. Look for backup in data directory.

---

Import/Export Issues

Import Fails

Solutions:

1. Check file format:

   • CSV must be comma-separated
   • Encoding must be UTF-8

2. Check required columns exist (at minimum: title).

3. Try smaller subset first.

4. Check for special characters in data.

Export Creates Empty File

Solutions:

1. Check filter isn't hiding all tasks.

2. Check write permissions on target directory.

3. Try different export location.

---

SSH/Remote Issues

Display Issues Over SSH

Solutions:

1. Forward locale:

   ssh -o SendEnv=LANG user@host

2. Set TERM:

   export TERM=xterm-256color

3. Check SSH config allows UTF-8.

Slow Over SSH

Solutions:

1. Enable compression:

   ssh -C user@host

2. Disable animations in config.

3. Use mosh instead of ssh for better latency handling.

---

Getting Help

If these solutions don't work:

1. Run with debug logging:

   taskflow -vvv --log-file /tmp/taskflow.log

2. Check the log file for errors.

3. Report issue with:

   • TaskFlow version (taskflow --version)
   • Operating system
   • Terminal emulator
   • Relevant log output

---

See Also

• FAQ - Frequently asked questions
• Configuration - Config reference
• Installation - Installation guide