Fixing Task-master AI Task Not Found

🔍 Root Problem

Task-master CLI was showing different results than the tasks.json file content:

  • JSON file: Contained 7 QR system tasks with proper progress
  • CLI output: “No tasks found” and “Found 0 tags”
  • MCP tools: Also showing 0 tasks

🛠️ Issues Discovered & Fixed

Issue #1: MCP Configuration Error

Problem:

"taskmaster-ai": {
  "command": "bun",
  "args": ["run", "task-master-ai"],  // ❌ Wrong: treats it as package script
  "env": { "OPENAI_API_KEY": "..." }
}

Solution:

"taskmaster-ai": {
  "command": "bun", 
  "args": ["x", "task-master-ai"],    // ✅ Correct: runs global command
  "env": { "OPENAI_API_KEY": "..." }
}

Why: bun run looks for package scripts, bun x executes global CLI tools like npx.


Issue #2: Incorrect JSON Structure

Problem – Nested tags structure:

{
  "version": "1.0.0",
  "tags": {                    // ❌ Wrong: nested structure
    "master": {
      "name": "master",        // ❌ Redundant field
      "tasks": [...]
    }
  }
}

Solution – Top-level tags:

{
  "version": "1.0.0", 
  "master": {                  // ✅ Correct: top-level tag
    "tasks": [...],
    "metadata": {              // ✅ Correct: metadata structure
      "created": "...",
      "updated": "...",
      "description": "..."
    }
  }
}

Why: Task-master expects tags as top-level objects, not nested under a “tags” container.


Issue #3: Reserved Tag Name Behavior

Problem:

  • "master" is a reserved tag name in task-master
  • Cannot be created using add-tag master command
  • Has special handling and initialization behavior

Solution:

  • Understand that “master” is pre-defined and reserved
  • Manual creation requires exact structure matching
  • Use other tag names (development, feature-branch, etc.) for additional contexts

Issue #4: API Key Mismatch

Problem:

// MCP has OpenAI key
"env": { "OPENAI_API_KEY": "sk-..." }

// But config uses different providers
"models": {
  "main": { "provider": "anthropic", "modelId": "claude-..." },
  "research": { "provider": "perplexity", "modelId": "sonar-pro" }
}

Solution:
Either update MCP keys to match providers OR change config to use OpenAI models.


🔧 Step-by-Step Fix Process

1. Fix MCP Configuration

# Edit ~/.cursor/mcp.json or project/.cursor/mcp.json
# Change: "args": ["run", "task-master-ai"]
# To:     "args": ["x", "task-master-ai"]

2. Fix JSON Structure

# Before - nested structure:
{
  "tags": { "master": { "name": "master", "tasks": [...] } }
}

# After - top-level structure:
{
  "master": { 
    "tasks": [...], 
    "metadata": { "created": "...", "description": "..." } 
  }
}

3. Test & Verify

# Should now work:
task-master tags          # Shows available tags
task-master list          # Shows tasks with progress
task-master next          # Shows next recommended task

# MCP tools should also work:
# get_tasks, add_task, set_task_status, etc.

⚠️ Key Lessons Learned

  1. MCP Args Format Matters:
  • ["run", "script"] = package script
  • ["x", "command"] = global CLI tool
  1. Task-master JSON Structure:
  • Tags are top-level objects, not nested
  • "master" is reserved with special behavior
  • Metadata goes in metadata object, not mixed with tag definition
  1. API Key Consistency:
  • MCP environment keys must match configured model providers
  • Or vice versa – update config to use available API keys
  1. Debugging Process:
  • Always check both CLI and MCP tool outputs
  • Verify JSON syntax with jq
  • Compare working vs. non-working structures
  • Test tags recognition separately from task listing

📋 Quick Diagnostic Commands

# Test MCP connection
task-master --version

# Check JSON syntax
jq . .taskmaster/tasks/tasks.json

# Verify tag structure  
task-master tags

# Test task listing
task-master list

# Check model configuration
task-master models

This troubleshooting guide should help anyone facing similar task-master issues! The key insight was understanding that task-master expects a flat tag structure rather than the nested format that seems more intuitive.

Example of Working tasks.json

{
  "version": "1.0.0",
  "projectName": "QR Code Platform",
  "projectDescription": "QR-Code Receipt Validation & Redemption Platform",
  "createdAt": "2025-01-27T12:00:00.000Z",
  "master": {
    "tasks": [
      {
        "id": 1,
        "title": "Database Schema Setup",
        "description": "Create comprehensive database schema with tables for customers, receipts, QR tokens, and audit logging",
        "status": "done",
        "priority": "high",
        "dependencies": [],
        "details": "✅ COMPLETED: Created comprehensive database schema with all 8 QR system tables + 4 auth tables. Includes proper relationships, constraints, and indexes for optimal performance.",
        "testStrategy": "Verify all tables created with proper relationships and constraints in PostgreSQL database",
        "subtasks": []
      },
      {
        "id": 2,
        "title": "Webhook Trigger Endpoint",
        "description": "Build webhook endpoint to receive receipt validation triggers and initiate QR generation workflow",
        "status": "done", 
        "priority": "high",
        "dependencies": [1],
        "details": "✅ COMPLETED: Implemented webhook endpoint at /api/generate-qr with proper HMAC-SHA256 authentication, payload validation, and error handling.",
        "testStrategy": "Test webhook with sample payload using HMAC authentication",
        "subtasks": []
      },
      {
        "id": 3,
        "title": "Token Creation & QR Encoding",
        "description": "Implement secure token generation and QR code creation with watermarks and branding",
        "status": "done",
        "priority": "high", 
        "dependencies": [1, 2],
        "details": "✅ COMPLETED: Built complete token generation system with secure random tokens, QR encoding with custom styling, watermarks, and error handling.",
        "testStrategy": "Generate test QR codes and verify they contain correct token data and branding",
        "subtasks": []
      },
      {
        "id": 4,
        "title": "QR Delivery System",
        "description": "Implement system to deliver generated QR codes via email, SMS, or API response",
        "status": "pending",
        "priority": "high",
        "dependencies": [3],
        "details": "Build flexible delivery system supporting multiple channels (email, SMS, webhook callback) with proper templating, retry logic, and delivery confirmation tracking.",
        "testStrategy": "Test delivery via all supported channels with success/failure tracking",
        "subtasks": []
      },
      {
        "id": 5,
        "title": "Redemption & Void APIs", 
        "description": "Create APIs for QR code redemption validation and voiding unredeemed codes",
        "status": "pending",
        "priority": "high",
        "dependencies": [4],
        "details": "Implement redemption validation endpoint with fraud detection, void functionality for unredeemed codes, and comprehensive audit logging for all redemption attempts.",
        "testStrategy": "Test successful redemption, duplicate redemption prevention, and void operations",
        "subtasks": []
      },
      {
        "id": 6,
        "title": "Anti-Fraud Controls",
        "description": "Implement comprehensive fraud detection and prevention measures",
        "status": "pending", 
        "priority": "medium",
        "dependencies": [5],
        "details": "Build fraud detection system with rate limiting, IP tracking, device fingerprinting, suspicious pattern detection, and automated blocking mechanisms.",
        "testStrategy": "Test fraud detection with various attack scenarios and verify blocking mechanisms",
        "subtasks": []
      },
      {
        "id": 7,
        "title": "Admin & Ops Dashboard",
        "description": "Create real-time dashboard for monitoring QR system performance and managing operations", 
        "status": "pending",
        "priority": "medium",
        "dependencies": [6],
        "details": "Build comprehensive dashboard with real-time metrics, QR generation/redemption tracking, fraud alerts, system health monitoring, and administrative controls.",
        "testStrategy": "Verify all dashboard features work correctly with real-time data updates and proper authentication",
        "subtasks": []
      }
    ],
    "metadata": {
      "created": "2025-01-27T12:00:00.000Z",
      "updated": "2025-01-27T12:00:00.000Z",
      "description": "Main development tasks for QR-Code Receipt Validation Platform"
    }
  },
  "development": {
    "tasks": [],
    "metadata": {
      "created": "2025-07-01T05:48:05.886Z",
      "updated": "2025-07-01T05:48:05.889Z",
      "description": "Development tasks for QR platform"
    }
  }
}

Leave a Reply

Your email address will not be published. Required fields are marked *