GDT

English

简体中文

English

简体中文

Appearance

Troubleshooting ​

Solutions to common issues.

Installation Issues ​

TaskWarrior Not Found ​

Error: TaskWarrior not detected

Check installation:

bash
task --version

If not installed, follow the Installation Guide.

Check PATH:

bash
which task
# Should output /usr/bin/task or similar

If installed but not found, add to PATH:

bash
export PATH=$PATH:/usr/local/bin

TaskWarrior Version Too Low ​

Error: TaskWarrior version too low (2.x.x)
GDT requires TaskWarrior 3.0 or higher

Upgrade TaskWarrior:

bash
brew upgrade task
bash
sudo add-apt-repository ppa:taskwarrior/taskwarrior
sudo apt update && sudo apt install taskwarrior

API Key Not Configured ​

Error: Please set ANTHROPIC_API_KEY environment variable

  1. Get API key: console.anthropic.com

  2. Set environment variable:

    bash
    export ANTHROPIC_API_KEY=sk-ant-your-key

  3. Or create .env file:

    bash
    echo "ANTHROPIC_API_KEY=sk-ant-your-key" > .env

Permission Error ​

Error: Cannot access ~/.gdt/ directory

Fix permissions:

bash
chmod 755 ~/.gdt/
chmod 644 ~/.gdt/*.json

Recreate directory structure:

bash
mkdir -p ~/.gdt/sessions ~/.gdt/task-context ~/.gdt/usage

API Errors ​

Network Connection Failed ​

Error: Cannot connect to API server

Check connectivity:

bash
curl https://api.anthropic.com

If using proxy:

bash
export HTTPS_PROXY=http://your-proxy:port

Rate Limit Exceeded ​

Error: Too many API requests (429)

Wait the indicated time and retry. Consider upgrading your API plan if this happens frequently.

Invalid API Key ​

Error: API Key invalid or expired
  1. Verify key format (should start with sk-ant-)
  2. Check status at console.anthropic.com
  3. Create a new key if expired

Response Timeout ​

Error: API response timeout
  • Check network stability
  • Try a simpler request
  • Wait and retry

TaskWarrior Errors ​

Database Locked ​

Error: TaskWarrior database is locked

Find other processes:

bash
ps aux | grep task

Force unlock (use caution):

bash
pkill -f "task "
rm ~/.task/task.lock

UDA Configuration Conflict ​

Error: UDA 'gdt.complexity' configuration conflict
  1. Check ~/.taskrc for conflicting definitions
  2. Remove conflicting lines
  3. Re-run GDT to auto-configure

Data Corruption ​

Error: TaskWarrior data file corrupted

Run diagnostics:

bash
task diagnostics

Attempt repair:

bash
task rc.confirmation=off repair

Restore from backup:

bash
cp ~/.task.backup/* ~/.task/

Session Issues ​

Session Won't Load ​

Error: Cannot load session data

Start fresh:

bash
gdt --new

Or delete corrupted session:

bash
rm ~/.gdt/sessions/current.json

Conversation History Lost ​

Possible causes:

  • History disabled in privacy settings
  • Session files deleted
  • Used --new flag

Check settings:

/privacy status

Re-enable if needed:

/privacy enable history

Performance Issues ​

Slow Startup ​

Check task count:

bash
task count

Archive old tasks:

bash
task completed end.before:1month delete

Slow Responses ​

  • Simplify your requests
  • Check network latency
  • Try during off-peak hours

Debugging ​

Enable debug logging:

bash
DEBUG=gdt:* gdt

Debug specific modules:

bash
DEBUG=gdt:llm gdt          # AI calls
DEBUG=gdt:taskwarrior gdt  # Task operations
DEBUG=gdt:session gdt      # Session management

Export diagnostics:

bash
gdt --diagnostics > diagnostics.txt

Getting Help ​

If these solutions don't work:

  1. Check documentation: getdone.today
  2. Run diagnostics: gdt --diagnostics
  3. Describe the issue with error messages and steps to reproduce

Copyright © 2026 GDT