mastra-ai/mastra · error · FactoryRuleValidationError

Factory rule version is required.

Error message

Factory rule version is required.

What it means

defaultFactoryRules requires an explicit, non-empty version string because the built-in rule defaults are versioned. If input.version is missing, not a string, or blank/whitespace, a FactoryRuleValidationError is thrown before any rules are merged. This guards against silently generating unversioned rule sets.

Source

Thrown at mastracode/factory/src/rules/defaults.ts:653

  return result;
}

export function mergeFactoryRuleOverrides(
  base: FactoryRulesOverrides,
  overrides: FactoryRulesOverrides = {},
): Omit<FactoryRules, 'version'> {
  return {
    work: mergeBoardRules(base.work, overrides.work),
    review: mergeBoardRules(base.review, overrides.review),
    tools: mergeToolRules(base.tools, overrides.tools),
    github: mergeGithubRules(base.github, overrides.github),
    linear: mergeLinearRules(base.linear, overrides.linear),
  };
}

export function defaultFactoryRules(input: { version: string; overrides?: FactoryRulesOverrides }): FactoryRules {
  if (typeof input?.version !== 'string' || input.version.trim().length === 0) {
    throw new FactoryRuleValidationError('Factory rule version is required.');
  }

  const rules: FactoryRules = {
    version: input.version.trim(),
    ...mergeFactoryRuleOverrides(BUILT_IN_DEFAULTS, input.overrides),
  };
  assertFactoryRules(rules);
  return rules;
}

export function builtInFactoryRules(): FactoryRules {
  return defaultFactoryRules({ version: DEFAULT_FACTORY_RULE_VERSION });
}

View on GitHub (pinned to 75dd419e61)

Solutions

1. Pass a non-empty version string: defaultFactoryRules({ version: '2024-01' }) — it is trimmed before use.
2. Fill in the missing env/config value that supplies the version and validate it at startup.
3. If loading from user config, fall back to a pinned default version explicitly.

Example fix

// before
defaultFactoryRules({ overrides: userOverrides });
// after
defaultFactoryRules({ version: '2024-01', overrides: userOverrides });

function assertRulesVersion(v: unknown): string {
  if (typeof v !== 'string' || v.trim().length === 0) throw new Error('version required');
  return v.trim();
}
defaultFactoryRules({ version: assertRulesVersion(config.rulesVersion), overrides });

function hasVersion(input: unknown): input is { version: string; overrides?: FactoryRulesOverrides } {
  return typeof input === 'object' && input !== null &&
    typeof (input as any).version === 'string' && (input as any).version.trim().length > 0;
}

try {
  rules = defaultFactoryRules({ version });
} catch (e) {
  if (e instanceof FactoryRuleValidationError) rules = defaultFactoryRules({ version: FALLBACK_VERSION });
  else throw e;
}

When it happens

Trigger: Calling defaultFactoryRules({ version: ... }) with version undefined, null, a non-string, an empty string, or a whitespace-only string — e.g. defaultFactoryRules({}) or defaultFactoryRules({ version: config.rulesVersion }) where config.rulesVersion is unset.

Common situations: Environment variable for the rules version not set, config schema not validating the version field, upgrading the factory and forgetting the new required parameter, or passing the overrides object as the first argument by mistake.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• ${label} must be an object.
• Factory rules must be an object.
• Cookie password must be at least 32 characters. Set WORKOS_C
• ${label} contains an unsupported field.
• Rule metadata is too large.

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