alibaba/open-code-review · error

max_tokens must be positive

Error message

max_tokens must be positive

What it means

Template.Validate enforces invariants after a template is loaded or constructed. MaxTokens is the per-request token budget for the LLM; if it is zero or negative the request cannot be sized correctly, so Validate returns 'max_tokens must be positive'. Callers typically hit this after building a Template programmatically or from a manifest where MAX_TOKENS was absent/zero.

Source

Thrown at internal/config/template/template.go:314

// and MEMORY_COMPRESSION_TASK).
func (t *ScanTemplate) ApplyLanguage(lang string) {
	instruction := "\n\nAlways respond in " + resolveLang(lang) + "."
	applyLanguage(&t.MainTask, instruction)
	if t.PlanTask != nil {
		applyLanguage(t.PlanTask, instruction)
	}
	if t.DedupTask != nil {
		applyLanguage(t.DedupTask, instruction)
	}
	if t.ProjectSummaryTask != nil {
		applyLanguage(t.ProjectSummaryTask, instruction)
	}
	applyLanguage(&t.MemoryCompressionTask, instruction)
}

func (t *Template) Validate() error {
	if t.MaxTokens <= 0 {
		return fmt.Errorf("max_tokens must be positive")
	}
	if t.MaxToolRequestTimes <= 0 {
		return fmt.Errorf("max_tool_request_times must be positive")
	}
	if t.MaxReviewRounds < 0 {
		return fmt.Errorf("max_review_rounds must not be negative")
	}
	if len(t.MainTask.Messages) == 0 {
		return fmt.Errorf("main_task.messages must not be empty")
	}
	return nil
}

// Validate checks that a ScanTemplate has the minimum fields populated.
func (t *ScanTemplate) Validate() error {
	if t.MaxTokens <= 0 {
		return fmt.Errorf("scan: max_tokens must be positive")
	}

View on GitHub (pinned to 5cf97d0d15)

Solutions

1. Set MaxTokens to a positive value appropriate for your model (e.g. 4096) before calling Validate
2. If loading from a manifest, add a MAX_TOKENS key with a positive integer to task_template.json and rebuild
3. Audit template-construction code paths to ensure every field assignment (MaxTokens, MaxToolRequestTimes, ...) is copied, not just the conversations
4. Call Validate() immediately after constructing/loading so the failure surfaces before any LLM request is attempted

Example fix

// before
tpl := &template.Template{MaxToolRequestTimes: 5, MainTask: mainTask}
if err := tpl.Validate(); err != nil { ... }
// after
tpl := &template.Template{MaxTokens: 4096, MaxToolRequestTimes: 5, MainTask: mainTask}
if err := tpl.Validate(); err != nil { ... }

func checkTemplate(t *template.Template) error {
	if t == nil || t.MaxTokens <= 0 {
		return fmt.Errorf("caller bug: MaxTokens must be > 0, got %d", t.MaxTokens)
	}
	return t.Validate()
}

if err := tpl.Validate(); err != nil {
	if strings.Contains(err.Error(), "max_tokens must be positive") {
		tpl.MaxTokens = 4096 // apply sane default
		err = tpl.Validate()
	}
	if err != nil { return err }
}

When it happens

Trigger: Calling (*Template).Validate() when t.MaxTokens <= 0 — e.g. a hand-written templateManifest JSON missing MAX_TOKENS, a Template literal with MaxTokens unset, or code copying manifest fields while skipping MaxTokens.

Common situations: Creating a custom Template in Go and forgetting to set MaxTokens; a stripped-down custom task_template.json without MAX_TOKENS; copy-pasting template construction code that leaves the zero value; tests building a minimal Template to check another invariant.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• invalid config: %w
• max_tool_request_times must be positive
• main_task.messages must not be empty
• load scan template: %w
• invalid scan template: %w

AI-assisted analysis of alibaba/open-code-review@5cf97d0d15 (2026-09-02). Data as JSON: /api/errors/6880e8e5bbd8ff35. Report an issue: GitHub.