configDirName must be a single directory name without path s

Error message

configDirName must be a single directory name without path separators or traversal components, got: "${configDirName}"

What it means

validateConfigDirName() rejects configDirName values that are absolute paths, contain path separators ('/' or '\\'), or are traversal components ('.' or '..'). configDirName must be a single safe directory segment because the SDK joins it under a parent config directory; anything path-like could escape that directory. The thrown message echoes the offending value.

Source

Thrown at mastracode/sdk/src/constants.ts:22

export const DEFAULT_CONFIG_DIR = '.mastracode';

/**
 * Validate that a configDirName is a safe single directory name.
 * Rejects absolute paths, path separators, and traversal components.
 */
export function validateConfigDirName(configDirName: string): void {
  if (configDirName.trim().length === 0) {
    throw new Error('configDirName must be a non-empty directory name');
  }

  if (
    path.isAbsolute(configDirName) ||
    configDirName.includes('/') ||
    configDirName.includes('\\') ||
    configDirName === '..' ||
    configDirName === '.'
  ) {
    throw new Error(
      `configDirName must be a single directory name without path separators or traversal components, got: "${configDirName}"`,
    );
  }
}

// Default OM model - using gemini-3.5-flash for efficiency
export const DEFAULT_OM_MODEL_ID = process.env.DEFAULT_OM_MODEL_ID ?? 'google/gemini-3.5-flash';

// Default OM thresholds — per-thread overrides are loaded from thread metadata
export const DEFAULT_OBS_THRESHOLD = 30_000;
export const DEFAULT_REF_THRESHOLD = 40_000;

View on GitHub (pinned to 75dd419e61)

Solutions

Pass only the leaf directory name (e.g. '.mastra-code'), not a full or partially joined path.
Strip separators/traversal from user input before calling, e.g. take path.basename(input) or reject it yourself.
Use path.basename on absolute values to derive a safe single segment, then re-validate with validateConfigDirName if it is exported.

Example fix

// before
createMastraCodeAgentController({ configDirName: '/home/me/.config/mastra' });
// after
const configDirName = '.mastra-code';
createMastraCodeAgentController({ configDirName });

Defensive patterns

Strategy: validation

Validate before calling

function isSafeDirName(v) {
  return (
    typeof v === 'string' &&
    v.trim().length > 0 &&
    !path.isAbsolute(v) &&
    !v.includes('/') &&
    !v.includes('\\') &&
    v !== '.' && v !== '..'
  );
}

Type guard

function isSingleDirSegment(v: unknown): v is string {
  return typeof v === 'string' && /^[^/\\.][^/\\]*$/.test(v) && v !== '..';
}

Try / catch

try {
  validateConfigDirName(candidate);
} catch (err) {
  console.error(`Invalid configDirName: ${candidate}`);
  process.exitCode = 2;
}

Prevention

Pass only the leaf directory name; construct the full path inside your app, not in configDirName.
Never pass values derived from path.join or absolute user paths.
Run validateConfigDirName (or an equivalent regex) on user input before controller creation.

When it happens

Trigger: createMastraCodeAgentController({ configDirName: ... }) with values like '/etc/mastra', 'foo/bar', 'a\\b', '.', or '..' — the isAbsolute/includes/== checks in the source all route to this throw.

Common situations: Users passing a full config path ('/home/me/.config/mastra') where only the leaf directory name is expected; Windows-style separators leaking from path building; '.' or '..' from careless defaults; joining user input with path.join before handing it to the SDK.

Related errors

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/8eb841ac22976f54. Report an issue: GitHub.