TaskTrove Documentation

Appearance

Troubleshooting ​

This guide helps you resolve common issues when running TaskTrove.

⚠️ Permission Error ​

Error Message:

Unable to access data directory. Check volume mounts and permissions.

Root Cause ​

TaskTrove cannot access the /app/data directory inside the container, typically due to missing host directory or lacking read/write permissions.

Your data is stored in the mounted data directory (e.g. ./data) on your host system, and mounted to /app/data inside the container.

This file is automatically created when TaskTrove starts successfully, unless the container does not have read/write permissions to the mounted data directory.

Quick Fix ​

Step 1: Create the data directory

bash
mkdir -p ./data

Step 2: Run TaskTrove with proper volume mounting

bash
docker run -p 3000:3000 -v ./data:/app/data -d --restart=always --name tasktrove ghcr.io/dohsimpson/tasktrove

Note the -v flag, which mounts the ./data directory from your host system to the /app/data directory inside the container.

Step 3: Check Permissions If the directory exists but TaskTrove still can't access it:

bash
# Set proper permissions
chmod 755 ./data

# For persistent permission issues, match container user
sudo chown -R 1000:1000 ./data

Verify Setup ​

Check that TaskTrove can access the data directory:

bash
# View container logs
docker logs tasktrove

# Test data directory access
docker exec tasktrove ls -la /app/data
docker exec tasktrove cat /app/data/data.json

🔄 Data Migration Issues ​

TaskTrove automatically detects when your data needs to be migrated to support new features. Here's how to handle migration-related issues:

Migration Prompt Appears on Startup ​

What you'll see:

Data Migration Available
Your data needs to be migrated from version vX.X.X to vY.Y.Y.

Solution ​

  1. Optional but recommended: Manually back up your data first - See our Backup Guide
  2. Click "Migrate Now" to start the automatic migration
  3. The migration will:
    • Create a timestamped backup file (data.json.backup-[timestamp])
    • Convert data structures to support new features
    • Preserve all your existing tasks, projects, and labels

Migration Failed ​

If migration fails, your original data remains unchanged. The system creates an automatic backup before attempting migration, but doesn't automatically restore it. Common causes:

Corrupted data file:

bash
# Check if data.json is valid JSON
docker exec tasktrove cat /app/data/data.json | python -m json.tool

Insufficient permissions:

bash
# Ensure write permissions
chmod 755 ./data
docker exec tasktrove touch /app/data/test.txt

Rollback After Failed Migration ​

If you need to rollback after a failed migration attempt:

bash
# List backup files
docker exec tasktrove ls -la /app/data/*.backup-*

# Restore from a backup (replace timestamp with actual backup file)
docker exec tasktrove cp /app/data/data.json.backup-1234567890 /app/data/data.json

# Restart the container
docker restart tasktrove

Note: After rollback, you'll be running the old data format with the new TaskTrove version. For full compatibility, downgrade TaskTrove to the previous version:

bash
# Stop and remove current container
docker stop tasktrove
docker rm tasktrove

# Run with specific version tag (e.g., v0.2.0)
docker run -p 3000:3000 -v ./data:/app/data -d --restart=always --name tasktrove ghcr.io/dohsimpson/tasktrove:v0.2.0

🔐 Blocked by Authentication Screen After Upgrade ​

What you'll see:

After upgrading to v0.7.0+, you're unable to access TaskTrove and are stuck at the login screen, creating a password fails with error.

Root Cause ​

This happens when you set the AUTH_SECRET environment variable before completing the data migration. The authentication system is enabled, but there's no password configured yet because migration wasn't completed first.

Solution ​

Step 1: Remove the AUTH_SECRET environment variable

bash
# Stop the container
docker stop tasktrove

# Remove the container
docker rm tasktrove

# Restart WITHOUT AUTH_SECRET
docker run -p 3000:3000 -v ./data:/app/data -d --restart=always --name tasktrove ghcr.io/dohsimpson/tasktrove

Step 2: Complete the data migration

  1. Access TaskTrove Web UI without authentication
  2. Follow the migration prompts in the web UI
  3. Wait for migration to complete successfully

Step 3: Add authentication (optional)

Once migration is complete, you can now safely enable password protection:

bash
# Stop the container
docker stop tasktrove
docker rm tasktrove

# Restart WITH AUTH_SECRET
docker run -p 3000:3000 -v ./data:/app/data -e AUTH_SECRET=your-secret-key -d --restart=always --name tasktrove ghcr.io/dohsimpson/tasktrove

See the Installation Guide for details on generating a secure AUTH_SECRET.

Step 4: Create your password

  1. Access TaskTrove at http://localhost:3000
  2. Create your password in the web UI

Prevention ​

When upgrading to v0.7.0+ with password protection, always follow this order:

  1. ✅ Upgrade to v0.7.0+ without AUTH_SECRET
  2. ✅ Complete data migration in web UI
  3. ✅ Set AUTH_SECRET environment variable
  4. ✅ Restart container
  5. ✅ Create password in web UI