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

${label} is not readable: ${dirPath}

Error message

${label} is not readable: ${dirPath}

What it means

Thrown by assertReadableDir when the directory exists and is a directory, but fs.access with R_OK fails — the current process lacks read permission. This isolates a permission problem from a missing/wrong-type path.

Source

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

    return path.join(this.bmadDir, name);
  }
  moduleConfig(name) {
    return path.join(this.bmadDir, name, 'config.yaml');
  }
}

async function assertReadableDir(dirPath, label) {
  const stat = await fs.stat(dirPath).catch(() => null);
  if (!stat) {
    throw new Error(`${label} does not exist: ${dirPath}`);
  }
  if (!stat.isDirectory()) {
    throw new Error(`${label} is not a directory: ${dirPath}`);
  }
  try {
    await fs.access(dirPath, fs.constants.R_OK);
  } catch {
    throw new Error(`${label} is not readable: ${dirPath}`);
  }
}

async function assertReadableFile(filePath, label) {
  const stat = await fs.stat(filePath).catch(() => null);
  if (!stat) {
    throw new Error(`${label} does not exist: ${filePath}`);
  }
  if (!stat.isFile()) {
    throw new Error(`${label} is not a file: ${filePath}`);
  }
  try {
    await fs.access(filePath, fs.constants.R_OK);
  } catch {
    throw new Error(`${label} is not readable: ${filePath}`);
  }
}

View on GitHub (pinned to b70486b9bd)

Solutions

1. Grant read access: `chmod +r <dirPath>` or `chown` it to the current user.
2. Run the installer as a user that owns the BMAD source tree.
3. Check for a read-only container mount and remount read-write or fix ownership.

await fs.access(dirPath, fs.constants.R_OK); // throws EACCES if unreadable

try {
  await assertReadableDir(dirPath, label);
} catch (error) {
  if (error.message.includes('is not readable')) { /* fix perms */ }
  throw error;
}

When it happens

Trigger: InstallPaths.create() validates the BMAD source root and the directory is present but the OS denies read access to the running user (EACCES).

Common situations: Running the installer as a different user than the one that owns the directory, directories created with restrictive umask, or running inside a container/sandbox with a read-mask on the mount.

Related errors

• ${label} is not readable: ${filePath}
• ${label}: permission denied creating directory: ${dirPath}
• ${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/69804c3efc25ada2. Report an issue: GitHub.