{"record":{"id":"b15cb527a9bd21c1","repo":"gastownhall/beads","slug":"worktree-removal-mode-is-absent-or-invalid","errorCode":null,"errorMessage":"worktree removal mode is absent or invalid","messagePattern":"worktree removal mode is absent or invalid","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/worktreeremove/policy.go","lineNumber":172,"sourceCode":"\treturn Mutation{TargetPath: plan.targetPath, Force: plan.mode == Force}\n}\n\n// Cleanup returns the exact managed-ignore cleanup approved by Prepare.\nfunc (plan Plan) Cleanup() (Cleanup, bool) {\n\tif plan.managedIgnoreEntry == \"\" {\n\t\treturn Cleanup{}, false\n\t}\n\treturn Cleanup{Entry: plan.managedIgnoreEntry}, true\n}\n\nfunc (plan Plan) valid() bool {\n\treturn plan.approved && (plan.mode == Normal || plan.mode == Force) && plan.targetPath != \"\"\n}\n\n// Prepare validates the initial observations and returns an approved plan.\nfunc Prepare(request Request, facts PrepareFacts) (Plan, error) {\n\tif request.Mode != Normal && request.Mode != Force {\n\t\treturn Plan{}, fmt.Errorf(\"worktree removal mode is absent or invalid\")\n\t}\n\tswitch facts.Target {\n\tcase PrimaryWorktree:\n\t\treturn Plan{}, fmt.Errorf(\"cannot remove the primary worktree\")\n\tcase CurrentWorktree:\n\t\treturn Plan{}, fmt.Errorf(\"cannot remove the worktree containing the running command\")\n\tcase RegisteredTarget:\n\tdefault:\n\t\treturn Plan{}, fmt.Errorf(\"registered worktree target is absent or invalid\")\n\t}\n\tif facts.Registration != Present || facts.RegisteredPath == \"\" ||\n\t\tfacts.TargetDir != Present || facts.GitAdminDir != Present ||\n\t\tfacts.GitMarker != Present || facts.Head != Present {\n\t\treturn Plan{}, fmt.Errorf(\"registered worktree target is absent or invalid\")\n\t}\n\tif facts.CommonDir != Matched {\n\t\treturn Plan{}, fmt.Errorf(\"target common git directory does not match repository\")\n\t}","sourceCodeStart":154,"sourceCodeEnd":190,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/worktreeremove/policy.go#L154-L190","documentation":"worktreeremove.Prepare rejects a Request whose Mode is neither Normal nor Force (e.g. the zero value of the Mode type). Prepare is a pure validation gate: it refuses to produce a Plan until the caller supplies a valid removal mode. This guards against accidentally building a removal plan from an uninitialized Request.","triggerScenarios":"Calling Prepare with a zero-value Request{} or with Request{Mode: <unset/unknown mode constant>}; constructing the Request programmatically and forgetting to set Mode.","commonSituations":"Struct literal missing the Mode field; deserializing a request from JSON/flags where Mode was not provided; a refactor adding a new mode value not yet accepted by policy.","solutions":["Set Request.Mode explicitly to worktreeremove.Normal or worktreeremove.Force before calling Prepare.","If Mode comes from user input, validate/map the string to a valid Mode constant first and surface a usage error.","Check that you are not passing a zero-value Request literal; fill in Target and other facts too.","If a new Mode was added, update Prepare's acceptance check to include it."],"exampleFix":"// before\nplan, err := worktreeremove.Prepare(worktreeremove.Request{Target: worktreeremove.RegisteredTarget}, facts)\n\n// after\nplan, err := worktreeremove.Prepare(worktreeremove.Request{\n    Target: worktreeremove.RegisteredTarget,\n    Mode:   worktreeremove.Normal,\n}, facts)","handlingStrategy":"validation","validationCode":"if req.Mode != worktreeremove.Normal && req.Mode != worktreeremove.Force {\n    return fmt.Errorf(\"mode must be Normal or Force before calling Prepare\")\n}\nplan, err := worktreeremove.Prepare(req, facts)","typeGuard":"func validMode(m worktreeremove.Mode) bool {\n    return m == worktreeremove.Normal || m == worktreeremove.Force\n}","tryCatchPattern":"plan, err := worktreeremove.Prepare(req, facts)\nif err != nil && strings.Contains(err.Error(), \"mode is absent or invalid\") {\n    return fmt.Errorf(\"specify --mode=normal or --mode=force\")\n}","preventionTips":["Never construct Request literals without setting Mode explicitly.","Use vet/linters or a constructor helper that requires Mode.","Map CLI flags to Mode constants with explicit defaults and errors on unknown values."],"tags":["validation","worktree","git","policy"],"backgroundTag":"missing-or-invalid-parameter","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}