mastra-ai/mastra · error · TripWire

TokenLimiterProcessor: System messages alone exceed token li

Error message

TokenLimiterProcessor: System messages alone exceed token limit. Requests cannot be completed by removing system messages.

What it means

TokenLimiterProcessor counts tokens for system messages plus a fixed conversation overhead (TOKENS_PER_CONVERSATION); if that sum already meets or exceeds maxTokens, no request containing the system messages could ever fit. Since system messages must be sent for the LLM to work, the processor throws a TripWire with retry:false to fail fast instead of producing an invalid request.

Source

Thrown at packages/core/src/processors/processors/token-limiter.ts:174

      throw new TripWire('TokenLimiterProcessor: No messages to process. Cannot send LLM a request with no messages.', {
        retry: false,
      });
    }

    // Budget against the full system message set that will reach the model
    // (untagged + tagged buckets), not just the untagged view exposed via args.
    const allSystemMessages = messageList.getAllSystemMessages();
    let systemTokens = 0;
    for (const msg of allSystemMessages) {
      systemTokens += await this.countCoreSystemMessageTokens(msg);
    }

    const limit = this.maxTokens;

    // If system messages alone exceed the token limit (accounting for conversation overhead),
    // throw TripWire - can't send LLM a request with only system messages
    if (systemTokens + TokenLimiterProcessor.TOKENS_PER_CONVERSATION >= limit) {
      throw new TripWire(
        'TokenLimiterProcessor: System messages alone exceed token limit. Requests cannot be completed by removing system messages.',
        { retry: false, metadata: { systemTokens, limit } },
      );
    }

    // Calculate remaining budget for non-system messages (accounting for conversation overhead)
    const remainingBudget = limit - systemTokens - TokenLimiterProcessor.TOKENS_PER_CONVERSATION;

    // Process non-system messages in reverse order (newest first)
    const messagesToKeep: MastraDBMessage[] = [];
    let currentTokens = 0;

    // Iterate through messages in reverse to prioritize recent messages
    for (let i = messages.length - 1; i >= 0; i--) {
      const message = messages[i];
      if (!message) continue;

      const messageTokens = await this.countInputMessageTokens(message);

View on GitHub (pinned to 75dd419e61)

Solutions

Increase maxTokens so it exceeds system-prompt tokens plus TOKENS_PER_CONVERSATION overhead.
Shorten the system prompt / instructions (trim or move static content out of system messages).
Remove the TokenLimiterProcessor or raise the limit for that agent if the context window genuinely allows it.
Measure actual system token count (countTokens on the system message) and set maxTokens with headroom above it.

Example fix

// before
new TokenLimiterProcessor({ maxTokens: 1000 }); // system prompt is 1200 tokens
// after
new TokenLimiterProcessor({ maxTokens: 8000 }); // > systemTokens + overhead

Defensive patterns

Strategy: validation

Validate before calling

const processor = new TokenLimiterProcessor({ maxTokens });
const systemText = messages.filter(m => m.role === 'system' && typeof m.content === 'string').map(m => m.content).join('');
if (processor.countTokens(systemText) + 1000 >= maxTokens) {
  throw new Error('maxTokens must exceed system prompt tokens + conversation overhead');
}

Try / catch

try {
  await agent.generate(input);
} catch (e) {
  if (TripWire.isTripWire?.(e) || e?.name === 'TripWire') {
    // e.metadata: { systemTokens, limit } — raise maxTokens or shorten system prompt
  } else throw e;
}

Prevention

Set maxTokens well above measured system-prompt tokens plus overhead.
Unit-test the processor with your real system prompt.
Keep system prompts short; move static context to retrieval.

When it happens

Trigger: processInputStep (via runStep) computes systemTokens from messageList.getAllSystemMessages() and systemTokens + TOKENS_PER_CONVERSATION >= this.maxTokens. Happens when the processor is constructed with a maxTokens smaller than the token count of the system prompt plus overhead.

Common situations: Configuring TokenLimiterProcessor({ maxTokens }) with a value tuned only for user messages while the agent has a large system prompt/instructions; shrinking maxTokens after growing memory instructions; misreading maxTokens as the non-system budget.

Related errors

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