What causes "Warning: Could not read agents directory ${agentsDir}:" in davila7/claude-code-templates?

Check permissions on the agents directory shown in the message

Warning: Could not read agents directory ${agentsDir}:

Error message

Warning: Could not read agents directory ${agentsDir}:

What it means

A warning from agent discovery: fs operations over the .claude/agents directory threw (permissions, missing dir edge case not previously guarded, EMFILE). The method returns whatever agents it collected so far.

Source

Thrown at cli-tool/src/analytics.js:1769

   * @returns {Promise<Array>} Array of agent objects
   */
  async loadAgentsFromDirectory(agentsDir, level, projectName = null) {
    const agents = [];
    
    try {
      const files = await fs.readdir(agentsDir);
      
      for (const file of files) {
        if (file.endsWith('.md')) {
          const filePath = path.join(agentsDir, file);
          const agentData = await this.parseAgentFile(filePath, level, projectName);
          if (agentData) {
            agents.push(agentData);
          }
        }
      }
    } catch (error) {
      console.warn(chalk.yellow(`Warning: Could not read agents directory ${agentsDir}:`, error.message));
    }
    
    return agents;
  }

  /**
   * Parse agent markdown file
   * @param {string} filePath - Path to agent file
   * @param {string} level - 'user' or 'project'
   * @param {string} projectName - Name of project (if project level)
   * @returns {Promise<Object|null>} Agent object or null if parsing failed
   */
  async parseAgentFile(filePath, level, projectName = null) {
    try {
      const content = await fs.readFile(filePath, 'utf8');
      const stats = await fs.stat(filePath);
      
      // Parse YAML frontmatter

View on GitHub (pinned to a0851ed10c)

Solutions

Check permissions on the agents directory shown in the message
Raise ulimit -n if you see EMFILE during large scans
Re-run the scan — transient races self-heal
Ignore; partial agent list is returned

Defensive patterns

Strategy: try-catch

Validate before calling

// Guard before scanning
const st = await fs.stat(agentsDir).catch(() => null);
if (!st?.isDirectory()) return agents; // nothing to scan

Try / catch

try { /* scan agents dir */ }
catch (error) {
  console.warn(`Could not read agents directory ${agentsDir}:`, error.message);
  return agents; // partial results
}

Prevention

Stat the directory before iterating
Run as the owning user; avoid sudo-launched scans
Raise ulimit -n for large-scale scans

When it happens

Trigger: readdir/readFile over ~/.claude/agents (or project agents dir) failing with EACCES/EMFILE/ENOENT racing directory deletion while iterating agent files.

Common situations: Agents directory owned by another user; too many open files during a large scan; directory removed mid-scan by the CLI itself.

Related errors

AI-assisted analysis of davila7/claude-code-templates@a0851ed10c (2026-08-28). Data as JSON: /api/errors/dd07bac34a7603cd. Report an issue: GitHub.