mastra-ai/mastra · error

Factory kickoff run ended in error.

Error message

Factory kickoff run ended in error.

What it means

The kickoff run completed but its recorded endReason was 'error', meaning the agent run itself failed. The dispatcher surfaces this as a throw so the pending start is marked failed and retried with backoff, keeping the Factory card alive instead of silently consuming the kickoff. It distinguishes genuine run failure from timeout/abort cases so operators can diagnose the underlying agent error.

Source

Thrown at mastracode/factory/src/rules/dispatcher.ts:994

              // "processed" signal, so wait for the in-flight run to end and
              // redeliver into the idle session unconditionally — the
              // generation-scoped dedupeKey defeats inbox dedupe and the
              // kickoff key keeps a duplicate run bounded, while a dropped
              // kickoff strands the card forever.
              if (!(await waitForAgentEndOrTimeout(agentEnd, this.#skillCompletionObservationTimeoutMs))) {
                throw new Error('Factory kickoff is waiting on a run that has not ended.');
              }
              armAgentEnd();
              settled = await sendKickoff(`factory-kickoff:${record.kickoffKey}:retry:${record.attempts}`);
              if (settled?.action !== 'wake') {
                throw new Error('Factory kickoff was queued onto an ending run and never reached the agent.');
              }
            }
            const observed = await waitForAgentEndOrTimeout(agentEnd, this.#skillCompletionObservationTimeoutMs);
            if (!observed) {
              throw new Error('Factory kickoff run terminal event was not observed before timeout.');
            } else if (endReason === 'error') {
              throw new Error('Factory kickoff run ended in error.');
            } else if (endReason === 'aborted') {
              // Retryable for the same reason as skill decisions: the dominant
              // cause is the process going away underneath the run, not a
              // deliberate stop, and a spurious retry is bounded by
              // MAX_ATTEMPTS while a dead card costs a human a manual nudge.
              throw new Error('Factory kickoff run was aborted before it finished.');
            }
          } finally {
            unsubscribe();
          }
        },
      );
      const completed = await this.#storage.completePendingStart(leaseIdentity(record, this.#ownerId), new Date());
      if (!completed) throw new Error('Factory kickoff lease was lost before completion.');
    } catch (error) {
      await this.#storage.failPendingStart({
        ...leaseIdentity(record, this.#ownerId),
        now: new Date(),

View on GitHub (pinned to 75dd419e61)

Solutions

1. Inspect the agent run's error details/traces to find the root cause before assuming dispatcher problems.
2. Verify credentials for the session owner (startedBy) are valid — primed credentials may be expired/revoked.
3. Confirm model availability and rate limits with your provider.
4. Let the retry deliver a fresh kickoff; if errors persist, fix the underlying tool/input error the run keeps hitting.

// verify credentials and provider health before kickoff
await primeCredentials({ orgId, userId: startedBy });
const healthy = await checkModelProviderHealth(modelId);
if (!healthy) throw new Error('model provider unavailable; defer kickoff');

try {
  await dispatcher.dispatch(record);
} catch (e) {
  if (String(e?.message).includes('ended in error')) {
    const cause = await fetchLastRunError(record); // inspect agent run traces
    await fixOrRequeue(record, cause);
  } else throw e;
}

When it happens

Trigger: The agent run started from the Factory kickoff terminated with endReason === 'error' — model API failure, tool exception, invalid input to the agent, or an unhandled error in the run pipeline.

Common situations: Model provider outages or rate limits during the run; a tool invoked by the agent threw; malformed work-item content fed to the agent; misconfigured model credentials (note the dispatcher primes credentials from startedBy before starting).

Related errors

• Factory kickoff is waiting on a run that has not ended.
• Factory kickoff run terminal event was not observed before t
• Factory kickoff run was aborted before it finished.
• error.message (dynamic; MaterializeError)
• ${initial.code}: ${initial.reason}

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