max depth %d of symlinks exceeded while reading %s

Error message

max depth %d of symlinks exceeded while reading %s

What it means

While reading a local action (./path) through its tar stream, act followed symlinks up to maxSylinkDepth times without ever reaching a regular file: after maxSymlinkDepth iterations the loop exits and this error reports the last path examined. It guards against symlink cycles (a -> b -> a) or chains longer than the configured depth.

Source

Thrown at pkg/runner/step_action_local.go:72

						return nil, nil, fs.ErrNotExist
					}
					treader := tar.NewReader(tars)
					header, err := treader.Next()
					if errors.Is(err, io.EOF) {
						return nil, nil, os.ErrNotExist
					} else if err != nil {
						return nil, nil, err
					}
					if header.FileInfo().Mode()&os.ModeSymlink == os.ModeSymlink {
						spath, err = symlinkJoin(spath, header.Linkname, cpath)
						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 := sal.readAction(ctx, sal.Step, actionDir, "", localReader(ctx), os.WriteFile)
		if err != nil {
			return err
		}

		sal.action = actionModel

		return sal.runAction(sal, actionDir, nil)(ctx)
	})
}

func (sal *stepActionLocal) post() common.Executor {
	return runStepExecutor(sal, stepStagePost, runPostStep(sal)).If(hasPostStep(sal)).If(shouldRunPostStep(sal))
}

View on GitHub (pinned to 4f41128141)

Solutions

Run `find .github/actions/<name> -type l -exec ls -l {} \;` and inspect every symlink for cycles or overly long chains.
Replace the chain with a single symlink or a real file.
Remove broken symlinks pointing at deleted files.

Example fix

# before
.github/actions/tool/action.yml -> alias.yml
.github/actions/tool/alias.yml  -> action.yml   # cycle
# after
.github/actions/tool/action.yml  # real file

Defensive patterns

Strategy: validation

Validate before calling

# detect symlink cycles / overlong chains in a local action dir
find .github/actions -type l -follow -lname '*cycle*' >/dev/null; python3 - <<'EOF'
import os
for root,_,files in os.walk('.github/actions'):
    for f in files:
        p=os.path.join(root,f)
        if os.path.islink(p):
            seen=set(); cur=p
            while os.path.islink(cur) and cur not in seen:
                seen.add(cur); cur=os.path.join(os.path.dirname(cur), os.readlink(cur))
            if cur in seen and os.path.islink(cur):
                print('cycle at', p)
EOF

Prevention

Never create mutually-referencing symlinks in action dirs.
Prefer real files over symlinks inside actions.
Keep symlink chains under the documented depth.

When it happens

Trigger: A local action directory contains a symlink loop (two symlinks pointing at each other) or a chain of symlinks longer than maxSymlinkDepth for a file act tries to read (typically action.yml / action.yaml resolution).

Common situations: Circular symlinks created accidentally in .github/actions/*; broken symlink chains on case-insensitive filesystems; deep symlink chains from monorepo tooling setups.

Related errors

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