plandex-ai/plandex · error

error unmarshalling settings-v2.json: %v

Error message

error unmarshalling settings-v2.json: %v

What it means

WriteCurrentBranch reads the plan's settings-v2.json and unmarshals it into types.PlanSettingsByAccount. If the file exists but its contents are not valid JSON (or don't match the expected shape), json.Unmarshal fails and the error is wrapped as 'error unmarshalling settings-v2.json: %v'. A missing file is intentionally tolerated and treated as empty settings.

Source

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

	}

	dir := filepath.Join(fs.HomePlandexDir, CurrentProjectId, CurrentPlanId)

	err := os.MkdirAll(dir, os.ModePerm)

	if err != nil {
		return fmt.Errorf("error creating plan dir: %v", err)
	}

	path := filepath.Join(dir, "settings-v2.json")

	var settingsByAccount *types.PlanSettingsByAccount

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

	if settingsByAccount == nil {
		settingsByAccount = &types.PlanSettingsByAccount{}
	}

	existingSettings := (*settingsByAccount)[auth.Current.UserId]

	if existingSettings == nil {
		existingSettings = &types.PlanSettings{}
	}

	existingSettings.Branch = branch
	(*settingsByAccount)[auth.Current.UserId] = existingSettings

View on GitHub (pinned to e2d772072e)

Solutions

1. Validate the file: run the wrapped JSON error's line/column through a JSON linter, or `python3 -m json.tool <path>` to find the syntax problem.
2. If the content is unrecoverable or from an old format, back it up and delete settings-v2.json — WriteCurrentBranch tolerates a missing file and will recreate it.
3. Avoid hand-editing; let the CLI rewrite the file by re-running the checkout/branch command after cleanup.

Example fix

$ cat ~/.plandex/<project>/<plan>/settings-v2.json | python3 -m json.tool
// invalid -> fix syntax, or:
$ mv settings-v2.json settings-v2.json.bak
$ plandex checkout main  # recreates settings-v2.json

path := filepath.Join(fs.HomePlandexDir, lib.CurrentProjectId, lib.CurrentPlanId, "settings-v2.json")
if b, err := os.ReadFile(path); err == nil {
    var v map[string]any
    if err := json.Unmarshal(b, &v); err != nil {
        return fmt.Errorf("settings-v2.json is corrupt: %w", err)
    }
}

if err := lib.WriteCurrentBranch(branch); err != nil {
    if strings.Contains(err.Error(), "error unmarshalling settings-v2.json") {
        os.Rename(path, path+".corrupt") // archive and let CLI recreate
        return lib.WriteCurrentBranch(branch)
    }
    return err
}

When it happens

Trigger: os.ReadFile succeeds but json.Unmarshal fails: file is empty/truncated, contains an array or string instead of an object keyed by account id, was hand-edited with syntax errors, or was written by an incompatible CLI version with a different schema.

Common situations: Manual editing of settings-v2.json breaking JSON syntax; an interrupted write (crash/power loss) leaving a truncated file; migrating from an older settings format whose JSON shape no longer unmarshals into PlanSettingsByAccount.

Understand the failure class

Background: JSON parse error: "Unexpected token" / "not valid JSON" / "failed to parse" — what JSON parsers are really complaining about — this error's family across 45 libraries.

Related errors

• error reading convo files: %v
• error getting plan file results: %v
• error getting latest plan build description: %v
• error getting contexts: %v
• error loading accounts: %v

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