{"record":{"id":"bcda271753a5f002","repo":"mastra-ai/mastra","slug":"factory-rules-tools-must-be-an-object","errorCode":null,"errorMessage":"Factory rules.tools must be an object.","messagePattern":"Factory rules\\.tools must be an object\\.","errorType":"validation","errorClass":"FactoryRuleValidationError","httpStatus":null,"severity":"error","filePath":"mastracode/factory/src/rules/validation.ts","lineNumber":167,"sourceCode":"      if (!isPlainObject(leaf)) throw new FactoryRuleValidationError(`${label}.${stage}.${source} must be an object.`);\n      assertExactKeys(leaf, ['onEnter', 'onExit'], `${label}.${stage}.${source}`);\n      for (const handler of Object.values(leaf)) {\n        if (handler !== undefined && typeof handler !== 'function') {\n          throw new FactoryRuleValidationError(`${label}.${stage}.${source} handlers must be functions.`);\n        }\n      }\n    }\n  }\n}\n\nexport function assertFactoryRules(rules: unknown): asserts rules is FactoryRules {\n  if (!isPlainObject(rules)) throw new FactoryRuleValidationError('Factory rules must be an object.');\n  assertExactKeys(rules, ['version', 'work', 'review', 'tools', 'github', 'linear'], 'Factory rules');\n  boundedString(rules.version, 'Factory rule version', MAX_VERSION_LENGTH);\n  validateBoardRules(rules.work, 'Factory rules.work');\n  validateBoardRules(rules.review, 'Factory rules.review');\n\n  if (!isPlainObject(rules.tools)) throw new FactoryRuleValidationError('Factory rules.tools must be an object.');\n  for (const [toolName, leaf] of Object.entries(rules.tools)) {\n    boundedString(toolName, 'Factory tool name', 128, IDENTIFIER_RE);\n    if (!isPlainObject(leaf))\n      throw new FactoryRuleValidationError(`Factory rules.tools.${toolName} must be an object.`);\n    assertExactKeys(leaf, ['onResult'], `Factory rules.tools.${toolName}`);\n    if (leaf.onResult !== undefined && typeof leaf.onResult !== 'function') {\n      throw new FactoryRuleValidationError(`Factory rules.tools.${toolName}.onResult must be a function.`);\n    }\n  }\n\n  if (!isPlainObject(rules.github)) throw new FactoryRuleValidationError('Factory rules.github must be an object.');\n  for (const [event, leaf] of Object.entries(rules.github)) {\n    enumValue(event, FACTORY_GITHUB_EVENTS, 'Factory GitHub event');\n    if (!isPlainObject(leaf)) throw new FactoryRuleValidationError(`Factory rules.github.${event} must be an object.`);\n    assertExactKeys(leaf, ['onEvent'], `Factory rules.github.${event}`);\n    if (leaf.onEvent !== undefined && typeof leaf.onEvent !== 'function') {\n      throw new FactoryRuleValidationError(`Factory rules.github.${event}.onEvent must be a function.`);\n    }","sourceCodeStart":149,"sourceCodeEnd":185,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/mastracode/factory/src/rules/validation.ts#L149-L185","documentation":"assertFactoryRules requires rules.tools to be a plain object mapping tool names to { onResult? } leaves. This error fires when rules.tools is missing, null, an array, or another non-plain-object value.","triggerScenarios":"rules.tools set to null/undefined/array while the other required keys (version, work, review, github, linear) are present, during prepare or defaultFactoryRules.","commonSituations":"Tools rules omitted from a hand-written config and set to null as placeholder; older config format without a tools section upgraded to a version requiring the key; YAML/JSON merging that produced an empty string or list.","solutions":["Set rules.tools to an object, using {} when there are no tool rules.","Migrate legacy configs that lacked a tools section to include tools: {}.","Check merge logic (e.g. deepMerge) for the tools key returning null on conflict."],"exampleFix":"// before\n{ version: '1', work: {}, review: {}, tools: null, github: {}, linear: {} }\n// after\n{ version: '1', work: {}, review: {}, tools: {}, github: {}, linear: {} }","handlingStrategy":"validation","validationCode":"if (rules.tools !== undefined && (rules.tools === null || typeof rules.tools !== 'object' || Array.isArray(rules.tools))) {\n  throw new Error('rules.tools must be a plain object (use {} if empty)');\n}","typeGuard":"const isToolsMap = (v: unknown): v is Record<string, { onResult?: (...args: never[]) => unknown }> =>\n  typeof v === 'object' && v !== null && !Array.isArray(v);","tryCatchPattern":"try {\n  assertFactoryRules(rules);\n} catch (e) {\n  if (e.name === 'FactoryRuleValidationError' && /rules\\.tools must be an object/.test(e.message)) {\n    rules.tools = {}; // or surface a config-migration error to the user\n    assertFactoryRules(rules);\n  } else throw e;\n}","preventionTips":["Include tools: {} in every rules template/scaffold.","When migrating configs between schema versions, add defaults for newly required sections.","Deep-merge configs with a policy that never yields null for object-typed keys."],"tags":["validation","structure","tools","factory-rules"],"backgroundTag":"schema-validation-failed","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}