bmad-code-org/BMAD-METHOD · error · Error

${label}: permission denied creating directory: ${dirPath}

Error message

${label}: permission denied creating directory: ${dirPath}

What it means

Thrown by ensureWritableDir when fs.ensureDir (recursive mkdir) fails with EACCES — the OS denied permission to create the directory. Surfaces a specific permission cause instead of a generic mkdir error.

Source

Thrown at tools/installer/core/install-paths.js:117

  }
  try {
    await fs.access(filePath, fs.constants.R_OK);
  } catch {
    throw new Error(`${label} is not readable: ${filePath}`);
  }
}

async function ensureWritableDir(dirPath, label) {
  const stat = await fs.stat(dirPath).catch(() => null);
  if (stat && !stat.isDirectory()) {
    throw new Error(`${label} exists but is not a directory: ${dirPath}`);
  }

  try {
    await fs.ensureDir(dirPath);
  } catch (error) {
    if (error.code === 'EACCES') {
      throw new Error(`${label}: permission denied creating directory: ${dirPath}`);
    }
    if (error.code === 'ENOSPC') {
      throw new Error(`${label}: no space left on device: ${dirPath}`);
    }
    throw new Error(`${label}: cannot create directory: ${dirPath} (${error.message})`);
  }

  try {
    await fs.access(dirPath, fs.constants.R_OK | fs.constants.W_OK);
  } catch {
    throw new Error(`${label} is not writable: ${dirPath}`);
  }
}

module.exports = { InstallPaths };

View on GitHub (pinned to b70486b9bd)

Solutions

1. Choose a writable target: pass `--directory` pointing at a location under your home dir.
2. Fix parent permissions: `chmod +w <parent>` or `chown` it to the current user.
3. Run with appropriate privileges only if installing into a system path is truly intended.

import { access } from 'node:fs/promises';
import path from 'node:path';
await access(path.dirname(dirPath), fs.constants.W_OK); // parent writable?

try {
  await ensureWritableDir(dirPath, label);
} catch (error) {
  if (error.message.includes('permission denied creating directory')) { /* fix parent perms */ }
  throw error;
}

When it happens

Trigger: InstallPaths.create() tries to create the project root or a _bmad subdirectory and mkdir is denied because the parent is not writable by the current user.

Common situations: Installing into a system directory, a parent owned by root while running as a normal user, or a read-only mount.

Related errors

• ${label} is not readable: ${dirPath}
• ${label} is not readable: ${filePath}
• ${label} is not writable: ${dirPath}
• ${label} does not exist: ${dirPath}
• ${label} is not a directory: ${dirPath}

AI-assisted analysis of bmad-code-org/BMAD-METHOD@b70486b9bd (2026-08-13). Data as JSON: /api/errors/95b28991eae6bd8e. Report an issue: GitHub.