What causes "Expected a directory: ${dirPath}" in affaan-m/ECC?

Verify with `ls -la ` that the target is a directory, not a file.

affaan-m/ECC · error · Error

Expected a directory

Error message

Expected a directory: ${dirPath}

What it means

ensureDirectory() validates that the given path is a directory via fs.statSync(dirPath).isDirectory(). If the path exists but is a regular file (or symlink to one), it throws 'Expected a directory: <dirPath>'.

Solutions

Verify with `ls -la <path>` that the target is a directory, not a file.
Point the script at the actual agents directory (e.g. `.gemini/agents`).
Remove or rename the file occupying the expected directory path and create the directory: `mkdir .gemini/agents`.
If it is a broken symlink, fix or remove it with `rm <symlink>` and recreate the directory.

Example fix

// before
$ node scripts/gemini-adapt-agents.js .gemini/AGENTS.md
Error: Expected a directory: .gemini/AGENTS.md
// after
$ node scripts/gemini-adapt-agents.js .gemini/agents

Defensive patterns

Strategy: type-guard

Validate before calling

const fs = require('fs');
const p = process.argv[2] || '.gemini/agents';
if (fs.existsSync(p) && !fs.statSync(p).isDirectory()) {
  console.error(`${p} is a file, not a directory`);
  process.exit(1);
}

Type guard

const isDirectory = (p) => { try { return fs.statSync(p).isDirectory(); } catch { return false; } };

Try / catch

try {
  adaptAgents(argv);
} catch (err) {
  if (/^Expected a directory:/.test(err.message)) {
    console.error(`${err.message}\nPass the agents folder (e.g. .gemini/agents), not a file.`);
    process.exit(1);
  }
  throw err;
}

Prevention

Point the script at a folder, never a file like AGENTS.md.
Use tab-completion on directories or append a trailing slash to force directory completion.
Check `ls -la` for symlinks that resolve to files.
After repo restructuring, confirm the directory still exists as a directory.

When it happens

Trigger: Passing a file path (e.g. .gemini/agents.md or a README) where the agents directory is expected, or a symlink pointing to a file instead of a directory.

Common situations: Pointing the script at a config file instead of the folder, a repo migration that replaced the directory with a file, or autocomplete selecting a file rather than the directory.

Related errors

AI-assisted analysis of affaan-m/ECC@8321021c54 (2026-09-16). Data as JSON: /api/errors/cbc6c41ed96bcfea. Report an issue: GitHub.

Appendix: source

Thrown at scripts/gemini-adapt-agents.js:53

  const positional = argv.filter(arg => !arg.startsWith('-'));
  if (positional.length > 1) {
    throw new Error('Expected at most one agents directory argument');
  }

  return {
    help: false,
    agentsDir: path.resolve(positional[0] || path.join(process.cwd(), '.gemini', 'agents')),
  };
}

function ensureDirectory(dirPath) {
  if (!fs.existsSync(dirPath)) {
    throw new Error(`Agents directory not found: ${dirPath}`);
  }

  if (!fs.statSync(dirPath).isDirectory()) {
    throw new Error(`Expected a directory: ${dirPath}`);
  }
}

function parseToolList(line) {
  const match = line.match(/^\s*tools\s*:\s*(.*)$/);
  if (!match) {
    return null;
  }

  return normalizeAgentTools(match[1]);
}

function adaptToolName(toolName) {
  const mapped = TOOL_NAME_MAP.get(toolName);
  if (mapped) {
    return mapped;
  }

View on GitHub (pinned to 8321021c54)