eyaltoledano/claude-task-master · error · TaskMasterError

NOT_FOUND

NOT_FOUND

Error message

Tasks file not found. Initialize the project first.

What it means

FileStorage.watchTasksFile throws a TaskMasterError with code NOT_FOUND when the tasks.json file it is asked to watch does not exist on disk. The watcher requires an existing file and will not start until the project is initialized.

Source

Thrown at packages/tm-core/src/modules/storage/adapters/file-storage/file-storage.ts:937

			return 'master';
		}
	}

	/**
	 * Watch for changes to tasks file
	 * Uses fs.watch with debouncing to detect file changes
	 */
	async watch(
		callback: (event: WatchEvent) => void,
		options?: WatchOptions
	): Promise<WatchSubscription> {
		const tasksPath = this.pathResolver.getTasksPath();
		const debounceMs = options?.debounceMs ?? 100;

		// Ensure file exists before watching
		const fileExists = await this.fileOps.exists(tasksPath);
		if (!fileExists) {
			throw new TaskMasterError(
				'Tasks file not found. Initialize the project first.',
				ERROR_CODES.NOT_FOUND,
				{ path: tasksPath }
			);
		}

		let debounceTimer: NodeJS.Timeout | undefined;
		let closed = false;

		const watcher = fs.watch(tasksPath, (eventType, filename) => {
			if (closed) return;
			if (filename && eventType === 'change') {
				if (debounceTimer) {
					clearTimeout(debounceTimer);
				}
				debounceTimer = setTimeout(() => {
					if (!closed) {
						callback({

View on GitHub (pinned to c0c98d367c)

Solutions

1. Run project initialization (tm init) to create the tasks file before watching
2. Check existsSync(pathResolver.getTasksPath()) before calling watchTasksFile
3. Verify the process working directory is the project root
4. Restore the deleted tasks.json (e.g. from git)

Example fix

// before
const watcher = await storage.watchTasksFile();
// after
const tasksPath = storage.pathResolver.getTasksPath();
if (!await storage.fileOps.exists(tasksPath)) {
  throw new Error(`Initialize first: missing ${tasksPath}`);
}
const watcher = await storage.watchTasksFile();

import { existsSync } from 'fs';
const tasksPath = pathResolver.getTasksPath();
if (!existsSync(tasksPath)) {
  throw new Error(`Tasks file missing at ${tasksPath}. Run: tm init`);
}
const watcher = await storage.watchTasksFile();

try {
  const watcher = await storage.watchTasksFile();
} catch (e) {
  if (e instanceof TaskMasterError && e.code === ERROR_CODES.NOT_FOUND) {
    await initProject();
    return await storage.watchTasksFile();
  }
  throw e;
}

When it happens

Trigger: Calling watchTasksFile() (with optional options like debounceMs) in a directory where getTasksPath() does not resolve to an existing file — i.e. before `tm init` or after the file was deleted/moved.

Common situations: Starting a watcher in a fresh checkout before initialization; wrong working directory so the resolver points elsewhere; tasks file deleted by a git clean or manual cleanup.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• Tag ${oldTag} not found - file doesn't exist
• Source tag ${sourceTag} not found or has no tasks
• NOT_FOUND
• branch does not exist: ${branchName}
• NOT_FOUND

AI-assisted analysis of eyaltoledano/claude-task-master@c0c98d367c (2026-08-29). Data as JSON: /api/errors/afad87bfc2f888c9. Report an issue: GitHub.