mastra-ai/mastra · error

configDirName must be a non-empty directory name

Error message

configDirName must be a non-empty directory name

What it means

validateConfigDirName() rejects configDirName values whose trimmed content is empty (whitespace-only strings included). The library stores per-project state under a single directory name, so it must have actual content before being joined into a path. It throws eagerly at controller creation time via createMastraCodeAgentController.

Source

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

import * as path from 'node:path';

// Default config directory name used for all project-level and global config paths.
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';

View on GitHub (pinned to 75dd419e61)

Solutions

1. Pass a non-empty single directory name, e.g. createMastraCodeAgentController({ configDirName: '.mastra-code' }).
2. If sourcing from env/CLI, coalesce to a default: configDirName ?? '.mastra-code', and trim before passing.
3. Guard with a trim check before calling the SDK so the failure surfaces at your config boundary.

Example fix

// before
createMastraCodeAgentController({ configDirName: process.env.MASTRA_CONFIG_DIR ?? '' });
// after
const configDirName = process.env.MASTRA_CONFIG_DIR?.trim() || '.mastra-code';
createMastraCodeAgentController({ configDirName });

function isValidConfigDirName(v) {
  return typeof v === 'string' && v.trim().length > 0;
}
if (!isValidConfigDirName(configDirName)) {
  throw new Error('configDirName must be a non-empty directory name');
}

function isNonEmptyString(v: unknown): v is string {
  return typeof v === 'string' && v.trim().length > 0;
}

try {
  controller = await createMastraCodeAgentController({ configDirName });
} catch (err) {
  if (err instanceof Error && err.message.includes('configDirName must be a non-empty directory name')) {
    controller = await createMastraCodeAgentController({ configDirName: '.mastra-code' });
  } else { throw err; }
}

When it happens

Trigger: Calling createMastraCodeAgentController({ configDirName: '' }) or with a whitespace-only value like ' ' (or an undefined-derived empty string from env/CLI parsing) — validateConfigDirName's first check (trim().length === 0) fires.

Common situations: Reading configDirName from an unset environment variable, an empty CLI flag value (--config-dir=), a JSON config field left as "", or defaulting with '' instead of a real name.

Related errors

• OpenAISDKAgent resumeData must include previousResponseId, c
• Google RBAC roleMapping is required.
• Cookie password must be at least 32 characters. Set OKTA_COO
• heartbeatMs must be a finite number no greater than ${MAX_TI
• Expected a PEM-encoded public key or certificate string for

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