mastra-ai/mastra · error

Failure in discover units step: ${discoverResult.error || 'U

Error message

Failure in discover units step: ${discoverResult.error || 'Unit discovery failed'}

What it means

The sibling check to the analyze-step failure: if discoverUnitsStep (which scans the cloned template for units/components) aborts, this error is thrown with the step's error or 'Unit discovery failed'. The workflow cannot order or install units without a successful discovery, so it aborts.

Source

Thrown at packages/agent-builder/src/workflows/template-builder/template-builder.ts:1625

    // Check for failure in clone step
    if (shouldAbortWorkflow(cloneResult)) {
      throw new Error(`Critical failure in clone step: ${cloneResult.error}`);
    }

    return cloneResult;
  })
  .parallel([analyzePackageStep, discoverUnitsStep])
  .map(async ({ getStepResult }) => {
    const analyzeResult = getStepResult(analyzePackageStep);
    const discoverResult = getStepResult(discoverUnitsStep);

    // Check for failures in parallel steps
    if (shouldAbortWorkflow(analyzeResult)) {
      throw new Error(`Failure in analyze package step: ${analyzeResult.error || 'Package analysis failed'}`);
    }

    if (shouldAbortWorkflow(discoverResult)) {
      throw new Error(`Failure in discover units step: ${discoverResult.error || 'Unit discovery failed'}`);
    }

    return discoverResult;
  })
  .then(orderUnitsStep)
  .map(async ({ getStepResult, getInitData }) => {
    const cloneResult = getStepResult(cloneTemplateStep);
    const initData = getInitData<AgentBuilderInputSchemaType>();
    return {
      commitSha: cloneResult.commitSha,
      slug: cloneResult.slug,
      targetPath: initData.targetPath,
    };
  })
  .then(prepareBranchStep)
  .map(async ({ getStepResult, getInitData }) => {
    const cloneResult = getStepResult(cloneTemplateStep);
    const packageResult = getStepResult(analyzePackageStep);

View on GitHub (pinned to 75dd419e61)

Solutions

  1. Read discoverResult.error in the message for the specific discovery failure and correct the template's unit files/layout
  2. Confirm the expected units/ directories and definition files exist in the cloned template at the chosen ref
  3. Validate unit definition files against the expected schema before publishing the template
  4. If 'Unit discovery failed' appears with no detail, enable step logging to capture the underlying exception
Defensive patterns

Strategy: validation

Validate before calling

export function assertUnitsPresent(dir: string, unitsDir = 'units') {
  const fs = require('node:fs');
  if (!fs.existsSync(`${dir}/${unitsDir}`)) throw new Error(`template missing ${unitsDir}/ directory`);
}
// check the cloned template layout before running discovery-dependent workflows

Type guard

export function discoverySucceeded(r: { units?: unknown[]; error?: string }): r is { units: unknown[]; error?: undefined } {
  return Array.isArray(r?.units) && !r.error;
}

Try / catch

try {
  await run.start({ ... });
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Failure in discover units step:')) {
    const detail = e.message.split(': ').slice(1).join(': ');
    // if detail === 'Unit discovery failed', enable step logging to find the real cause
  }
  throw e;
}

Prevention

When it happens

Trigger: discoverUnitsStep aborted while scanning the template directory: unit definition files missing or malformed, unreadable directories, or discovery conventions not met by the template layout.

Common situations: Templates restructured to a layout the discoverer doesn't recognize, unit files with schema-invalid frontmatter/metadata, or a bad clone (wrong ref) that omits the unit directories entirely.

Related errors

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