Add automatic cache cleanup on version change

thallgren · thallgren · commit 51801d8d4b17 · 2026-02-09T04:07:34.000+01:00
Track the CLI version in a version.json file in the cache directory.
When a version mismatch is detected, quit running daemons and clear
stale cache entries (preserving logs) to prevent issues from leftover
files after an upgrade.

Signed-off-by: Thomas Hallgren &lt;thomas@tada.se&gt;
diff --git a/CHANGELOG.yml b/CHANGELOG.yml
@@ -52,6 +52,13 @@ items:
           the need for elevated privileges when using Telepresence. Currently available for amd64 architecture only
           due to dependency constraints.
         docs: install/client
+      - type: feature
+        title: Automatic cache cleanup on version change
+        body: >-
+          Telepresence now tracks its version in a version.json file in the cache directory. When the CLI detects
+          that the major.minor version differs from the running binary, it automatically quits running daemons and
+          clears stale cache entries (preserving logs). This prevents issues caused by leftover cache files from a
+          previous version. Patch and pre-release version changes do not trigger a cache cleanup.
   - version: 2.26.2
     date: (TBD)
     notes:
diff --git a/docs/release-notes.md b/docs/release-notes.md
@@ -20,6 +20,12 @@ New Linux package installers (.deb for Debian/Ubuntu and .rpm for Fedora/RHEL) a
 A new Windows installer (.exe) is now available that installs Telepresence with the root daemon configured as a Windows service. The installer bundles WinFSP and SSHFS-Win dependencies for volume mount support, adds Telepresence to the system PATH, and optionally installs the TelepresenceDaemon service. This eliminates the need for elevated privileges when using Telepresence. Currently available for amd64 architecture only due to dependency constraints.
 </div>
 
+## <div style="display:flex;"><img src="images/feature.png" alt="feature" style="width:30px;height:fit-content;"/><div style="display:flex;margin-left:7px;">Automatic cache cleanup on version change</div></div>
+<div style="margin-left: 15px">
+
+Telepresence now tracks its version in a version.json file in the cache directory. When the CLI detects that the major.minor version differs from the running binary, it automatically quits running daemons and clears stale cache entries (preserving logs). This prevents issues caused by leftover cache files from a previous version. Patch and pre-release version changes do not trigger a cache cleanup.
+</div>
+
 ## Version 2.26.2
 ## <div style="display:flex;"><img src="images/bugfix.png" alt="bugfix" style="width:30px;height:fit-content;"/><div style="display:flex;margin-left:7px;">Fix HTTP intercepts via telepresence compose failing when httpFilters or httpPaths are set</div></div>
 <div style="margin-left: 15px">
diff --git a/docs/release-notes.mdx b/docs/release-notes.mdx
@@ -26,6 +26,12 @@ New Linux package installers (.deb for Debian/Ubuntu and .rpm for Fedora/RHEL) a
 A new Windows installer (.exe) is now available that installs Telepresence with the root daemon configured as a Windows service. The installer bundles WinFSP and SSHFS-Win dependencies for volume mount support, adds Telepresence to the system PATH, and optionally installs the TelepresenceDaemon service. This eliminates the need for elevated privileges when using Telepresence. Currently available for amd64 architecture only due to dependency constraints.
   </Body>
 </Note>
+<Note>
+	<Title type="feature">Automatic cache cleanup on version change</Title>
+	<Body>
+Telepresence now tracks its version in a version.json file in the cache directory. When the CLI detects that the major.minor version differs from the running binary, it automatically quits running daemons and clears stale cache entries (preserving logs). This prevents issues caused by leftover cache files from a previous version. Patch and pre-release version changes do not trigger a cache cleanup.
+  </Body>
+</Note>
 ## Version 2.26.2
 <Note>
 	<Title type="bugfix">Fix HTTP intercepts via telepresence compose failing when httpFilters or httpPaths are set</Title>
diff --git a/pkg/client/cli/cmd/telepresence.go b/pkg/client/cli/cmd/telepresence.go
@@ -33,7 +33,12 @@ func Telepresence(ctx context.Context, args []string) *cobra.Command {
 		Args:              OnlySubcommands,
 		Short:             "Connect your workstation to a Kubernetes cluster",
 		Long:              longHelp,
-		PersistentPreRunE: output.SetFormat,
+		PersistentPreRunE: func(cmd *cobra.Command, args []string) error {
+			if err := output.SetFormat(cmd, args); err != nil {
+				return err
+			}
+			return ensureCacheVersion(cmd, args)
+		},
 		RunE:              RunSubcommands,
 		SilenceErrors:     true, // main() will handle it after .ExecuteContext() returns
 		SilenceUsage:      true, // our FlagErrorFunc will handle it
diff --git a/pkg/client/cli/cmd/versioncache.go b/pkg/client/cli/cmd/versioncache.go
@@ -0,0 +1,50 @@
+package cmd
+
+import (
+	"errors"
+	"io/fs"
+	"os"
+	"path/filepath"
+
+	"github.com/blang/semver/v4"
+	"github.com/spf13/cobra"
+
+	"github.com/telepresenceio/telepresence/v2/pkg/client/cache"
+	"github.com/telepresenceio/telepresence/v2/pkg/client/cli/connect"
+	"github.com/telepresenceio/telepresence/v2/pkg/filelocation"
+	"github.com/telepresenceio/telepresence/v2/pkg/version"
+)
+
+type versionFile struct {
+	Version semver.Version `json:"version"`
+}
+
+func ensureCacheVersion(cmd *cobra.Command, _ []string) error {
+	ctx := cmd.Context()
+	var vf versionFile
+	majorMinorMatch := false
+	if err := cache.LoadFromUserCache(ctx, &vf, "version.json"); err == nil {
+		majorMinorMatch = vf.Version.Major == version.Structured.Major && vf.Version.Minor == version.Structured.Minor
+		if majorMinorMatch {
+			return nil
+		}
+	}
+
+	// Quit all daemons (best effort, ignore errors).
+	connect.Quit(ctx)
+
+	// Clear cache except logs.
+	cacheDir := filelocation.AppUserCacheDir(ctx)
+	entries, err := os.ReadDir(cacheDir)
+	if err != nil && !errors.Is(err, fs.ErrNotExist) {
+		return err
+	}
+	for _, entry := range entries {
+		if entry.Name() == "logs" {
+			continue
+		}
+		os.RemoveAll(filepath.Join(cacheDir, entry.Name()))
+	}
+
+	return cache.SaveToUserCache(ctx, &versionFile{Version: version.Structured}, "version.json", cache.Public)
+}
