max depth %d of symlinks exceeded while reading %s

Error message

max depth %d of symlinks exceeded while reading %s

What it means

Remote-action counterpart of the local symlink-depth error: while reading files (action.yml, etc.) from the cached tar archive of a remote action, act followed maxSymlinkDepth symlinks (each constrained to stay within '.' via symlinkJoin) without reaching a regular file, and gives up with this error.

Source

Thrown at pkg/runner/step_action_remote.go:100

						tars, err := cache.GetTarArchive(ctx, sar.cacheDir, sar.resolvedSha, spath)
						if err != nil {
							return nil, nil, os.ErrNotExist
						}
						treader := tar.NewReader(tars)
						header, err := treader.Next()
						if err != nil {
							return nil, nil, os.ErrNotExist
						}
						if header.FileInfo().Mode()&os.ModeSymlink == os.ModeSymlink {
							spath, err = symlinkJoin(spath, header.Linkname, ".")
							if err != nil {
								return nil, nil, err
							}
						} else {
							return treader, tars, nil
						}
					}
					return nil, nil, fmt.Errorf("max depth %d of symlinks exceeded while reading %s", maxSymlinkDepth, spath)
				}
			}

			actionModel, err := sar.readAction(ctx, sar.Step, sar.resolvedSha, sar.remoteAction.Path, remoteReader(ctx), os.WriteFile)
			sar.action = actionModel
			return err
		}

		actionDir := fmt.Sprintf("%s/%s", sar.RunContext.ActionCacheDir(), safeFilename(sar.Step.Uses))
		gitClone := stepActionRemoteNewCloneExecutor(git.NewGitCloneExecutorInput{
			URL:         sar.remoteAction.CloneURL(),
			Ref:         sar.remoteAction.Ref,
			Dir:         actionDir,
			Token:       github.Token,
			OfflineMode: sar.RunContext.Config.ActionOfflineMode,
		})
		var ntErr common.Executor
		if err := gitClone(ctx); err != nil {

View on GitHub (pinned to 4f41128141)

Solutions

Inspect the action repo for symlink loops in the referenced path; report/avoid the action if broken.
Clear act's action cache directory so a fresh, clean archive is fetched.
Pin to an earlier ref of the action known to lack the loop, or vendor the action locally.

Defensive patterns

Strategy: fallback

Validate before calling

# verify a cached action archive has no symlink cycles
tar -tvf ~/.cache/act/<org>_<repo>.tar | awk '$1 ~ /^l/ {print $6, $NF}'  # inspect symlink -> target pairs for loops

Prevention

Pin third-party actions to reviewed full SHAs.
Clear the action cache if archives may be corrupted.
Vendor suspicious actions locally and review their tree.

When it happens

Trigger: A remote action's repository contains a symlink cycle or a symlink chain longer than maxSymlinkDepth in the path act reads (action metadata or run files); the archived tar records symlinks whose linknames chain indefinitely.

Common situations: A third-party action repo with circular symlinks (accidental or malicious probing); cache corruption replaying a malformed tar; repos that rely on build-time symlink resolution GitHub performs but which form a loop in raw archive form.

Related errors

AI-assisted analysis of nektos/act@4f41128141 (2026-08-15). Data as JSON: /api/errors/b57a9e51425def40. Report an issue: GitHub.