Failure in install step: ${installResult.error || 'Install f

Error message

Failure in install step: ${installResult.error || 'Install failed'}

What it means

After orderUnitsStep and installStep run, this map step checks shouldAbortWorkflow(installResult) and throws 'Failure in install step' with the installer's error or 'Install failed'. Dependency installation into the cloned template failed, so the build aborts before configuration/finishing steps.

Source

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

      packageInfo: packageResult,
    };
  })
  .then(packageMergeStep)
  .map(async ({ getInitData }) => {
    const initData = getInitData<AgentBuilderInputSchemaType>();
    return {
      targetPath: initData.targetPath,
    };
  })
  .then(installStep)
  .map(async ({ getStepResult, getInitData }) => {
    const cloneResult = getStepResult(cloneTemplateStep);
    const orderResult = getStepResult(orderUnitsStep);
    const installResult = getStepResult(installStep);
    const initData = getInitData<AgentBuilderInputSchemaType>();

    if (shouldAbortWorkflow(installResult)) {
      throw new Error(`Failure in install step: ${installResult.error || 'Install failed'}`);
    }
    return {
      orderedUnits: orderResult.orderedUnits,
      templateDir: cloneResult.templateDir,
      commitSha: cloneResult.commitSha,
      slug: cloneResult.slug,
      targetPath: initData.targetPath,
      variables: initData.variables,
    };
  })
  .then(programmaticFileCopyStep)
  .map(async ({ getStepResult, getInitData }) => {
    const copyResult = getStepResult(programmaticFileCopyStep);
    const cloneResult = getStepResult(cloneTemplateStep);
    const initData = getInitData<AgentBuilderInputSchemaType>();

    return {
      conflicts: copyResult.conflicts,

View on GitHub (pinned to 75dd419e61)

Solutions

Read installResult.error for the package manager's actual failure and address that dependency/registry issue
Run the install command manually inside the cloned template directory to reproduce and see full logs
Align the package manager version with the template's lockfile (e.g. correct corepack/pnpm version)
Check registry authentication for private packages and network access from the runtime environment
Retry on transient registry/network errors

Example fix

// before (template package.json)
"dependencies": { "left-pad": "^99.0.0" }
// after — pin a resolvable version
"dependencies": { "left-pad": "^1.3.0" }

Defensive patterns

Strategy: retry

Validate before calling

const { execSync } = require('node:child_process');
export function assertInstallable(dir: string, cmd = 'npm install --dry-run') {
  execSync(cmd, { cwd: dir, stdio: 'ignore' }); // throws if deps cannot resolve
}
// run in the cloned template dir before invoking install-dependent workflows

Type guard

export function installSucceeded(r: { error?: string; [k: string]: unknown }) {
  return r != null && !r.error;
}

Try / catch

try {
  await run.start({ ... });
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Failure in install step:')) {
    const cause = e.message.replace('Failure in install step: ', '');
    if (cause === 'Install failed') { /* enable install-step logs for the package-manager output */ }
    // retry transient registry errors with backoff
  }
  throw e;
}

Prevention

Pin resolvable dependency versions in template package.json and keep the lockfile in sync
Match the package manager version to the lockfile (corepack/packageManager field)
Configure registry auth tokens for private packages in the runtime environment
Pre-warm/verify registry access in CI and air-gapped environments

When it happens

Trigger: installStep aborted during package installation in the cloned templateDir: package manager (npm/pnpm/yarn) exited non-zero due to unresolvable dependency versions, missing lockfile compatibility, registry/network errors, or missing build tooling in the environment.

Common situations: Template pins dependencies that no longer resolve, private registry packages without auth tokens, lockfile generated by a different package-manager major version, peer-dependency conflicts, or offline/CI environments without network access to the registry.

Related errors

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