mastra-ai/mastra · error · MastraError

EXPERIMENT_TARGET_NOT_FOUND

EXPERIMENT_TARGET_NOT_FOUND

Error message

Target not found: ${experiment.targetType} "${experiment.targetId}"

What it means

After resolving the experiment's target (agent or workflow by type and id, optionally at a specific agentVersion), executeExperimentItem throws EXPERIMENT_TARGET_NOT_FOUND if nothing was resolved. The experiment record points at a target that no longer exists or isn't registered on the Mastra instance.

Source

Thrown at packages/core/src/datasets/experiment/item.ts:89

  const attempt = args.attempt ?? 0;

  if (experiment.targetType === null || experiment.targetId === null) {
    throw new MastraError({
      id: 'EXPERIMENT_HAS_NO_TARGET',
      text: `Experiment ${experiment.id} has no target; results must be ingested via submitExperimentResult`,
      domain: 'STORAGE',
      category: 'USER',
    });
  }

  const resolved = await resolveTarget(
    mastra,
    experiment.targetType,
    experiment.targetId,
    experiment.agentVersion ?? undefined,
  );
  if (!resolved) {
    throw new MastraError({
      id: 'EXPERIMENT_TARGET_NOT_FOUND',
      text: `Target not found: ${experiment.targetType} "${experiment.targetId}"`,
      domain: 'STORAGE',
      category: 'USER',
    });
  }

  // Scorer precedence: experiment scorerIds → item scorerIds → dataset scorerIds → none.
  let scorers: MastraScorer<any, any, any, any>[] = [];
  let scorerConfigError: ExecutionResult['error'] = null;
  if (experiment.scorerIds != null) {
    scorers = resolveScorers(mastra, [...new Set(experiment.scorerIds)]);
  } else if (item.scorerIds !== undefined) {
    const resolution = await createItemScorerResolver(mastra)(item.scorerIds);
    scorers = resolution.scorers;
    if (resolution.missingIds.length > 0) {
      scorerConfigError = {
        code: EXPERIMENT_ITEM_SCORER_NOT_FOUND,

View on GitHub (pinned to 75dd419e61)

Solutions

Verify the agent/workflow id in experiment.targetId exists on the Mastra instance you're executing against.
Re-create the experiment against an existing target, or update the experiment record's targetId.
If using agentVersion, ensure that version still exists or clear agentVersion to use the current one.
Register the missing agent/workflow in this environment's Mastra instance before running.

Example fix

// before
const experiment = await datasets.experiments.create({ targetType: 'agent', targetId: 'support-agent-v1', ... });
// after — verify target exists first
const agent = mastra.getAgent('support-agent-v1');
if (!agent) throw new Error('Agent support-agent-v1 not registered');
const experiment = await datasets.experiments.create({ targetType: 'agent', targetId: 'support-agent-v1', ... });

Defensive patterns

Strategy: validation

Validate before calling

const agent = mastra.getAgent(experiment.targetId);
if (!agent) throw new Error(`Target agent "${experiment.targetId}" is not registered in this Mastra instance`);

Type guard

function targetExists(mastra: Mastra, e: { targetType: string; targetId: string }): boolean {
  return e.targetType === 'agent'
    ? !!mastra.getAgent(e.targetId)
    : !!mastra.getWorkflow(e.targetId);
}

Try / catch

try {
  await runExperimentItem({ mastra, experiment, item });
} catch (err) {
  if (err?.id === 'EXPERIMENT_TARGET_NOT_FOUND') {
    logger.error(`Experiment ${experiment.id} references missing target ${experiment.targetId}`);
    return markRunFailed(runId, err);
  }
  throw err;
}

Prevention

Resolve the target from the same Mastra instance used for execution.
Avoid renaming/deleting agents with active experiments; check references first.
If pinning agentVersion, confirm the version exists before creating experiments.
Keep target ids consistent across environments via config, not literals.

When it happens

Trigger: experiment.targetId references an agent/workflow that was deleted or renamed; running against a different Mastra instance that doesn't register that agent; experiment.agentVersion pins a version that is gone; typo in targetId when creating the experiment.

Common situations: Renaming agents while old experiment runs still reference the old id; environment drift between dev/staging where agents differ; cleaning up agents with active experiments; rollback removing a pinned agentVersion.

Related errors

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