Troubleshooting¶

Common issues and solutions for TaskRepo.

Installation Issues¶

Command not found¶

Problem: tsk: command not found after installation

Solution:

For pipx:

python3 -m pipx ensurepath
# Restart terminal

For uv:

source $HOME/.cargo/env

Permission errors¶

Problem: Permission denied during installation

Solution: Don't use sudo

# Use pipx or uv instead
pipx install taskrepo

Configuration Issues¶

Config file not found¶

Problem: TaskRepo can't find configuration

Solution: Initialize TaskRepo

tsk init

Can't write to parent directory¶

Problem: Permission error when creating repositories

Solution: Check parent directory permissions or change location:

tsk config
# Select new parent directory

Git Issues¶

Sync conflicts¶

Problem: Merge conflicts during sync

Solution: Use conflict resolution strategies:

# Interactive resolution (default)
tsk sync --strategy interactive

# Keep local changes
tsk sync --strategy local

# Keep remote changes
tsk sync --strategy remote

No remote configured¶

Problem: "No remote configured" error

Solution: Add a git remote:

cd ~/tasks/tasks-work
git remote add origin https://github.com/user/tasks-work

Task Issues¶

Task not found¶

Problem: Can't find task by ID

Solution: 1. Check if task exists: tsk list --all 2. Try searching: tsk search "task name" 3. Task may be in different repository: tsk list --repo other-repo

Invalid task format¶

Problem: Task file won't parse

Solution: Check YAML frontmatter syntax

tsk edit <id>
# Fix YAML syntax errors

Getting More Help¶

If you're still stuck:

1. Check GitHub Issues
2. Ask in Discussions
3. File a bug report