What causes "purpose is required" in plandex-ai/plandex?

Pass a non-empty purpose string at the call site

purpose is required

Error message

purpose is required

What it means

ModelRequest was invoked with an empty purpose parameter. purpose selects/describes the model request use-case and is mandatory; the library validates it up front before building model config and messages. This is a caller-side input validation error, not a provider error.

Source

Thrown at app/server/model/model_request.go:78

	messages := params.Messages
	prediction := params.Prediction
	stop := params.Stop
	tools := params.Tools
	toolChoice := params.ToolChoice
	modelConfig := params.ModelConfig
	modelStreamId := params.ModelStreamId
	convoMessageId := params.ConvoMessageId
	buildId := params.BuildId
	modelPackName := params.ModelPackName
	purpose := params.Purpose
	sessionId := params.SessionId
	settings := params.Settings
	orgUserConfig := params.OrgUserConfig
	currentOrgId := auth.OrgId
	currentUserId := auth.User.Id

	if purpose == "" {
		return nil, fmt.Errorf("purpose is required")
	}

	baseModelConfig := modelConfig.GetBaseModelConfig(authVars, settings, orgUserConfig)

	messages = FilterEmptyMessages(messages)
	messages = CheckSingleSystemMessage(modelConfig, baseModelConfig, messages)
	inputTokensEstimate := GetMessagesTokenEstimate(messages...) + TokensPerRequest

	config := modelConfig.GetRoleForInputTokens(inputTokensEstimate, settings)
	modelConfig = &config

	if params.EstimatedOutputTokens != 0 {
		config = modelConfig.GetRoleForOutputTokens(params.EstimatedOutputTokens, settings)
		modelConfig = &config
	}

	log.Println("ModelRequest - modelConfig:")
	spew.Dump(modelConfig)

View on GitHub (pinned to e2d772072e)

Solutions

Pass a non-empty purpose string at the call site
Trace which caller (GenPlanName, buildValidate, etc.) passed the empty value
Add validation at your own boundary before calling ModelRequest
Check config/DB values feeding purpose for emptiness
Document required purpose values for new wrappers around ModelRequest

Example fix

// before
res, err := model.ModelRequest(ctx, auth, "", messages, params)
// after
purpose := "generate_plan_name"
if purpose == "" { return nil, errors.New("purpose missing") }
res, err := model.ModelRequest(ctx, auth, purpose, messages, params)

Defensive patterns

Strategy: validation

Validate before calling

if purpose == "" {
    return nil, errors.New("purpose must be set before calling ModelRequest")
}

Try / catch

res, err := model.ModelRequest(ctx, auth, purpose, messages, params)
if err != nil {
    if strings.Contains(err.Error(), "purpose is required") {
        return nil, fmt.Errorf("caller bug: purpose not provided: %w", err)
    }
    return nil, err
}

Prevention

Define purpose as a typed constant/enum so it can't be an empty string
Validate purpose at your API boundary before reaching ModelRequest
Review all wrappers (GenPlanName, buildValidate, ...) for purpose propagation
Add a unit test asserting each wrapper passes a non-empty purpose

When it happens

Trigger: Any call to ModelRequest with purpose == "" — e.g. GenPlanName, GenPipedDataName, GenNoteName, buildValidate, buildWholeFileFallback, or genPlanDescription passing an uninitialized/empty purpose string.

Common situations: Refactored call sites forgetting to set purpose; purpose derived from user input or config that is empty; a new helper built on ModelRequest omitting the field; empty DB/config value propagated into the call.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

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