plandex-ai/plandex · error

HomePlandexDir not set

Error message

HomePlandexDir not set

What it means

WriteCurrentPlan persists the current-plan pointer and returns 'HomePlandexDir not set' when the fs package's HomePlandexDir global is empty, meaning the Plandex home directory was never initialized for this process.

Source

Thrown at app/cli/lib/plans.go:16

package lib

import (
	"encoding/json"
	"fmt"
	"os"
	"path/filepath"
	"plandex-cli/auth"
	"plandex-cli/fs"
	"plandex-cli/types"
	"sync"
)

func WriteCurrentPlan(id string) error {
	if fs.HomePlandexDir == "" {
		return fmt.Errorf("HomePlandexDir not set")
	}

	if CurrentProjectId == "" || HomeCurrentPlanPath == "" {
		return fmt.Errorf("no current project")
	}

	var currentPlanSettingsByAccount *types.CurrentPlanSettingsByAccount

	bytes, err := os.ReadFile(HomeCurrentPlanPath)
	if err == nil {
		err = json.Unmarshal(bytes, &currentPlanSettingsByAccount)
		if err != nil {
			return fmt.Errorf("error unmarshalling current-plans-v2.json: %v", err)
		}
	} else if !os.IsNotExist(err) {
		return fmt.Errorf("error checking if current-plans-v2.json exists: %v", err)
	}

View on GitHub (pinned to e2d772072e)

Solutions

1. Ensure HOME (or the equivalent) is set and writable so ~/.plandex can be created
2. Run the CLI's normal init/bootstrap path before calling WriteCurrentPlan
3. Run `plandex` once interactively to create HomePlandexDir, then retry
4. Check that no code path overwrites/resets fs.HomePlandexDir to empty

Example fix

// before
HOME= plandex new myplan   # HomePlandexDir not set
// after
export HOME=/home/user
plandex new myplan

if os.Getenv("HOME") == "" {
	return fmt.Errorf("HOME must be set before using plandex")
}
if err := os.MkdirAll(filepath.Join(os.Getenv("HOME"), ".plandex"), 0o755); err != nil {
	return err
}

func plandexHomeReady() bool {
	return fs.HomePlandexDir != ""
}

if err := lib.WriteCurrentPlan(id); err != nil {
	if err.Error() == "HomePlandexDir not set" {
		// run CLI bootstrap/init, then retry
	}
	return err
}

When it happens

Trigger: Calling WriteCurrentPlan (via `cd` or `new`) before the CLI's fs initialization ran, or in an environment where the home directory resolution failed so fs.HomePlandexDir == "".

Common situations: HOME env var unset or empty (cron, CI, containers) so no ~/.plandex dir can be derived; calling library APIs without the CLI bootstrap; tests instantiating the package directly.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• error loading accounts: %v
• error getting server models input: %v
• invalid value: %s
• no project root found
• error checking custom models: %v

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