plandex-ai/plandex · error

Max tokens exceeded before adding context

Error message

Max tokens exceeded before adding context

What it means

Before adding plan context to the prompt, execTellPlan estimates tokens: tokensRemaining = tentativeMaxTokens - (sharedMsgsTokens + tokensWithoutContext). If tokensRemaining is negative, the base messages already exceed the stage's max token budget before context is even added, and a 500 ApiError "Max tokens exceeded before adding context" is sent. This is a guard against sending an oversized prompt to the LLM.

Source

Thrown at app/server/model/plan/tell_exec.go:247

			cacheControl:        true,
		})

		if state.currentStage.PlanningPhase == shared.PlanningPhaseTasks {
			if req.AutoContext {
				msg := types.ExtendedChatMessage{
					Role:    openai.ChatMessageRoleSystem,
					Content: []types.ExtendedChatMessagePart{},
				}
				for _, part := range planStageSharedMsgs {
					msg.Content = append(msg.Content, *part)
				}
				sharedMsgsTokens := model.GetMessagesTokenEstimate(msg)

				tokensRemaining := tentativeMaxTokens - (sharedMsgsTokens + tokensWithoutContext)

				if tokensRemaining < 0 {
					log.Println("tokensRemaining is negative")
					go notify.NotifyErr(notify.SeverityError, fmt.Errorf("tokensRemaining is negative"))

					active.StreamDoneCh <- &shared.ApiError{
						Type:   shared.ApiErrorTypeOther,
						Status: http.StatusInternalServerError,
						Msg:    "Max tokens exceeded before adding context",
					}
					return
				}

				planningPhaseOnlyMsgs = state.formatModelContext(formatModelContextParams{
					includeMaps:          false,
					smartContextEnabled:  req.SmartContext,
					includeApplyScript:   false, // already included in planStageSharedMsgs
					activeOnly:           true,
					activatePaths:        activatePaths,
					activatePathsOrdered: activatePathsOrdered,
					maxTokens:            int(float64(tokensRemaining) * 0.95), // leave a little extra room
				})

View on GitHub (pinned to e2d772072e)

Solutions

1. Reduce plan context — remove unneeded files from the context map so token estimates fit the budget.
2. Increase the model pack's max tokens (GetModelPack / effective max tokens settings) or switch to a larger-context model.
3. Start a new plan/branch or clear the conversation if the accumulated shared messages are the bulk of the tokens.
4. Trim custom rules/system prompt files if they are inflating sharedMsgsTokens.

Example fix

// before (model pack config)
"maxTokens": 8192 // too small for loaded context
// after
"maxTokens": 131072 // sized to the model's real context window

// estimate before calling Tell; match the server formula
estimated := model.GetMessagesTokenEstimate(msgs) + contextTokenEstimate
if estimated >= modelPack.CoderEffectiveMaxTokens() {
    return errors.New("context too large: trim plan context or raise maxTokens before telling")
}

apiErr := <-active.StreamDoneCh
if apiErr.Msg == "Max tokens exceeded before adding context" {
    // reduce context and retry with a smaller prompt
    plandexContextRemove(planId, "large-file.txt")
    return retryTell(planId, branch)
}

When it happens

Trigger: The sum of system/shared message tokens plus tokensWithoutContext exceeds tentativeMaxTokens for the current stage — a very large context map, huge custom system prompt/rules, or a model pack with a low GetCoderEffectiveMaxTokens / context max.

Common situations: Users loading many or very large files into plan context; custom model packs configured with an undersized maxTokens; switching to a smaller model via model pack change mid-plan; TellStage set to a stage whose model has a smaller budget than the accumulated conversation.

Related errors

• Token limit exceeded before adding conversation
• error adding plan context tokens: %v
• error building whole file: %w
• fast apply validation failed: %w
• error building validate loop: %w

AI-assisted analysis of plandex-ai/plandex@e2d772072e (2026-09-05). Data as JSON: /api/errors/15c8c225847756a6. Report an issue: GitHub.