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

Path expansion for ~${username} is not supported. Please use

Error message

Path expansion for ~${username} is not supported. Please use an absolute path or ~${path.sep}

What it means

Thrown by expandUserPath when the path starts with '~' but is neither '~' alone nor '~' + path.sep + rest — i.e. POSIX '~user' (home-for-another-user) syntax. The installer only resolves the current user's home via os.homedir(); other users' homes are not expanded.

Source

Thrown at tools/installer/ui.js:1676

    if (typeof inputPath !== 'string') {
      throw new TypeError('Path must be a string.');
    }

    let expanded = inputPath.trim();

    // Handle tilde expansion
    if (expanded.startsWith('~')) {
      if (expanded === '~') {
        expanded = os.homedir();
      } else if (expanded.startsWith('~' + path.sep)) {
        const pathAfterHome = expanded.slice(2); // Remove ~/ or ~\
        expanded = path.join(os.homedir(), pathAfterHome);
      } else {
        const restOfPath = expanded.slice(1);
        const separatorIndex = restOfPath.indexOf(path.sep);
        const username = separatorIndex === -1 ? restOfPath : restOfPath.slice(0, separatorIndex);
        if (username) {
          throw new Error(`Path expansion for ~${username} is not supported. Please use an absolute path or ~${path.sep}`);
        }
      }
    }

    // Resolve to the absolute path relative to the current working directory
    return path.resolve(expanded);
  }

  /**
   * Get configured IDEs from existing installation
   * @param {string} directory - Installation directory
   * @returns {Array} List of configured IDEs
   */
  async getConfiguredIdes(directory) {
    const { ExistingInstall } = require('./core/existing-install');
    const { Installer } = require('./core/installer');
    const installer = new Installer();
    const { bmadDir } = await installer.findBmadDir(directory);

View on GitHub (pinned to b70486b9bd)

Solutions

1. Use an absolute path: /home/otheruser/path or the actual home directory.
2. Use '~' (current user) or '~/subdir' only — these are the supported tilde forms.
3. Resolve the other user's home upstream (e.g. via getent passwd) and pass the absolute path.

Example fix

# before
#   --directory ~root/bmad
#
# after
#   --directory /root/bmad
#   --directory ~/bmad        # if running as the intended user

function isSupportedTildeForm(p) {
  if (typeof p !== 'string') return false;
  if (!p.startsWith('~')) return true;
  return p === '~' || p.startsWith('~' + path.sep);
}
if (!isSupportedTildeForm(options.directory)) {
  throw new Error('Use an absolute path; ~user syntax is not supported.');
}

function isSupportedTildeForm(p) {
  if (typeof p !== 'string' || !p.startsWith('~')) return true;
  return p === '~' || p.startsWith('~' + path.sep);
}

try {
  dir = ui.expandUserPath(options.directory);
} catch (e) {
  if (/Path expansion for ~.* is not supported/.test(e.message)) {
    // resolve the absolute home dir upstream and pass that instead
  } else { throw e; }
}

When it happens

Trigger: Passing --directory ~otheruser/path or --directory ~root (anything matching ~<name>... that isn't ~/).

Common situations: Copying a path from a root-user or another user's context; a cross-user deployment script using ~ for a different user; assuming full POSIX tilde expansion.

Related errors

• Path must be a string.
• version is not available when nothing is installed
• ${label} does not exist: ${dirPath}
• ${label} is not a directory: ${dirPath}
• ${label} is not readable: ${dirPath}

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