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

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.

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.

Appendix: 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)