What causes "Error building plan" in plandex-ai/plandex?

Check the server log for 'Error building plan: ' — the root cause is only there, not in the HTTP response.

Error building plan

Error message

Error building plan

What it means

modelPlan.Build returned an error while executing the plan's pending builds (applying file changes produced by the LLM). The handler logs it, reports it asynchronously, and responds 500 'Error building plan' (note: unlike the tell path, the underlying detail is NOT included in the response, only in server logs).

Source

Thrown at app/server/handlers/plans_exec.go:198

			settings:      settings,
			orgUserConfig: orgUserConfig,
		},
	)
	numBuilds, err := modelPlan.Build(modelPlan.BuildParams{
		Clients:       res.clients,
		AuthVars:      res.authVars,
		Plan:          plan,
		Branch:        branch,
		Auth:          auth,
		SessionId:     requestBody.SessionId,
		OrgUserConfig: orgUserConfig,
		Settings:      settings,
	})

	if err != nil {
		log.Printf("Error building plan: %v\n", err)
		go notify.NotifyErr(notify.SeverityError, fmt.Errorf("error building plan: %v", err))
		http.Error(w, "Error building plan", http.StatusInternalServerError)
		return
	}

	if numBuilds == 0 {
		log.Println("No builds were executed")
		go notify.NotifyErr(notify.SeverityInfo, fmt.Errorf("no builds were executed"))
		http.Error(w, shared.NoBuildsErr, http.StatusNotFound)
		return
	}

	if requestBody.ConnectStream {
		startResponseStream(r.Context(), w, auth, planId, branch, false)
	}

	log.Println("Successfully processed request for BuildPlanHandler")
}

func ConnectPlanHandler(w http.ResponseWriter, r *http.Request) {

View on GitHub (pinned to e2d772072e)

Solutions

Check the server log for 'Error building plan: <detail>' — the root cause is only there, not in the HTTP response.
Stop any other active tell/build on the plan+branch, then retry to clear lock contention.
Validate LLM provider keys/quota if the detail points at a model call failure.
Check disk space and permissions on the plan storage volume; repair with `plandex` plan health commands if the repo is dirty.
Retry the build; if a specific file edit keeps failing, remove/reload that context and re-run.

Example fix

// before: response hides the cause
http.Error(w, "Error building plan", http.StatusInternalServerError)
// after: include the detail like the tell path does
http.Error(w, "Error building plan: "+err.Error(), http.StatusInternalServerError)

Defensive patterns

Strategy: fallback

Validate before calling

// ensure no other operation holds the plan and provider key is present
if os.Getenv("OPENAI_API_KEY") == "" && len(req.ApiKeys) == 0 {
    return errors.New("missing model credentials for build")
}

Try / catch

if err := modelPlan.Build(params); err != nil {
    log.Printf("Error building plan: %v", err) // root cause is only in logs
    if isLockConflict(err) { stopPlan(); time.Sleep(2*time.Second); return retryBuild() }
    return fmt.Errorf("build failed; check server logs for detail: %w", err)
}

Prevention

Check server logs (not just the HTTP response) — the response omits the underlying detail.
Serialize tell→build per plan+branch; avoid concurrent clients.
Keep LLM keys funded/valid to prevent mid-stream provider failures.
Maintain free disk space and correct permissions on plan storage.

When it happens

Trigger: Build-plan POST where the build loop fails: git repo operations inside the plan's working copy fail, an LLM streaming call errors mid-build, file write/patch application fails, or the plan lock cannot be acquired.

Common situations: Concurrent modification of the plan branch (lock contention); LLM provider error mid-stream (quota, key revoked); filesystem full or permission issues on the server's plan storage; conflicting edits that cannot be applied.

Related errors

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