ahmetb/kubectx · error

HOME or USERPROFILE environment variable not set

Error message

HOME or USERPROFILE environment variable not set

What it means

Sentinel error in kubectxPrevCtxFile: cmdutil.CacheDir() returned an empty string because neither HOME nor USERPROFILE is set in the environment, so the tool cannot locate its cache directory to store/read the previous-context state file (~/.cache/kubectx/kubectx). Swap and switch operations depend on this path.

Source

Thrown at cmd/kubectx/state.go:29

// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package main

import (
	"errors"
	"fmt"
	"os"
	"path/filepath"

	"github.com/ahmetb/kubectx/internal/cmdutil"
)

func kubectxPrevCtxFile() (string, error) {
	dir := cmdutil.CacheDir()
	if dir == "" {
		return "", errors.New("HOME or USERPROFILE environment variable not set")
	}
	return filepath.Join(dir, "kubectx"), nil
}

// readLastContext returns the saved previous context
// if the state file exists, otherwise returns "".
func readLastContext(path string) (string, error) {
	b, err := os.ReadFile(path)
	if os.IsNotExist(err) {
		return "", nil
	}
	return string(b), err
}

// writeLastContext saves the specified value to the state file.
// It creates missing parent directories.
func writeLastContext(path, value string) error {
	dir := filepath.Dir(path)

View on GitHub (pinned to 12ad6fb22e)

Solutions

1. Set the HOME environment variable (USERPROFILE on Windows) before running kubectx
2. Ensure the shell environment is complete (e.g. in cron/CI set HOME explicitly)

When it happens

Trigger: Thrown at cmd/kubectx/state.go:29 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of ahmetb/kubectx@12ad6fb22e (2026-09-02). Data as JSON: /api/errors/e1f9f929ddd4abbc. Report an issue: GitHub.