fix: Fixing symlink issue on pre-existing provider cache entries

Author: yhakbar

docs/src/data/changelog/v1.0.4/stale-provider-cache-symlink.mdx

@@ -0,0 +1,10 @@
+---
+version: "v1.0.4"
+category: "bug-fixes"
+---
+
+#### Fixed `failed to create directory ...: file exists` from the provider cache server
+
+If a previous run had cached a provider by symlinking `~/.terraform.d/plugins/<provider>` into Terragrunt's own provider cache, and that user plugin directory was later moved or deleted, the symlink was left dangling. The next run failed with `failed to create directory ...: file exists` and refused to cache the provider.
+
+Terragrunt now removes a dangling symlink at the cache path on the next run and proceeds to download the provider. A non-symlink at that path is left in place and surfaced as an error.

internal/tf/cache/services/errors.go

@@ -0,0 +1,21 @@
+package services
+
+import (
+	"fmt"
+	"os"
+)
+
+// UnexpectedProviderCachePathError is returned when something other than a
+// Terragrunt-managed symlink occupies a provider's package path inside the
+// provider cache directory. Terragrunt only ever writes a directory (from a
+// fresh download) or a symlink (pointing at the user plugins directory) to
+// this path, so anything else is treated as user content and reported rather
+// than removed.
+type UnexpectedProviderCachePathError struct {
+	Path string
+	Mode os.FileMode
+}
+
+func (e *UnexpectedProviderCachePathError) Error() string {
+	return fmt.Sprintf("unexpected non-symlink at provider package path %q (mode %s); refusing to remove", e.Path, e.Mode)
+}

internal/tf/cache/services/provider_cache.go

@@ -321,6 +321,15 @@ func (cache *ProviderCache) warmUp(ctx context.Context) error {
 		return nil
 	}
 
+	// vfs.FileExists uses Stat, which follows symlinks. A dangling symlink
+	// (e.g. left over from a previous run that pointed at ~/.terraform.d/plugins
+	// before that directory was moved or deleted) reports as non-existent here
+	// but still trips MkdirAll downstream with "file exists". Remove only the
+	// symlink itself before the download or user-plugin symlink path runs.
+	if err := cache.removeStaleSymlink(fs); err != nil {
+		return err
+	}
+
 	if err := fs.MkdirAll(filepath.Dir(cache.packageDir), os.ModePerm); err != nil {
 		return errors.New(err)
 	}
@@ -411,6 +420,34 @@ func (cache *ProviderCache) newRequest(ctx context.Context, url string) (*http.R
 	return req, nil
 }
 
+// removeStaleSymlink removes a dangling symlink at cache.packageDir, if one is
+// present. The caller has already confirmed via vfs.FileExists (Stat-based)
+// that no real cached package is here. The only artifact this method deletes
+// is a symlink whose target has gone missing, typically because the user
+// moved or removed ~/.terraform.d/plugins after a prior run. A regular file
+// or directory at this path is unexpected and surfaces as an error rather
+// than a deletion.
+func (cache *ProviderCache) removeStaleSymlink(fs vfs.FS) error {
+	info, err := vfs.Lstat(fs, cache.packageDir)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return nil
+		}
+
+		return errors.Errorf("failed to inspect provider package path %q: %w", cache.packageDir, err)
+	}
+
+	if info.Mode()&os.ModeSymlink == 0 {
+		return &UnexpectedProviderCachePathError{Path: cache.packageDir, Mode: info.Mode()}
+	}
+
+	if err := fs.Remove(cache.packageDir); err != nil {
+		return errors.Errorf("failed to clear stale provider package symlink %q: %w", cache.packageDir, err)
+	}
+
+	return nil
+}
+
 func (cache *ProviderCache) removeArchive() error {
 	fs := cache.ProviderService.FS()
 

internal/vfs/vfs.go

@@ -95,6 +95,17 @@ func FileExists(vfs FS, path string) (bool, error) {
 	return false, err
 }
 
+// Lstat returns the FileInfo for the named path without following symlinks.
+// Filesystems that do not implement afero.Lstater fall back to Stat.
+func Lstat(fsys FS, path string) (os.FileInfo, error) {
+	if lstater, ok := fsys.(afero.Lstater); ok {
+		info, _, err := lstater.LstatIfPossible(path)
+		return info, err
+	}
+
+	return fsys.Stat(path)
+}
+
 // WriteFile writes data to a file on the given filesystem.
 func WriteFile(fs FS, filename string, data []byte, perm os.FileMode) error {
 	dir := filepath.Dir(filename)