hasura/graphql-engine · error

failed to resolve the symlink of the currently executed vers

Error message

failed to resolve the symlink of the currently executed version: %w

What it means

Realpath detected that the path is a symlink and os.Readlink failed to read its target. The symlink exists but its link table entry could not be read — typically EACCES on the containing directory, EIO, or a filesystem that mishandles the readlink syscall.

Source

Thrown at cli/plugins/paths/paths.go:112

// Realpath evaluates symbolic links. If the path is not a symbolic link, it
// returns the cleaned path. Symbolic links with relative paths return error.
func Realpath(path string) (string, error) {
	var op errors.Op = "paths.Realpath"

	s, err := os.Lstat(path)
	if err != nil {
		return "", errors.E(
			op,
			fmt.Errorf("failed to stat the currently executed path (%q): %w", path, err),
		)
	}

	if s.Mode()&os.ModeSymlink != 0 {
		if path, err = os.Readlink(path); err != nil {
			return "", errors.E(
				op,
				fmt.Errorf(
					"failed to resolve the symlink of the currently executed version: %w",
					err,
				),
			)
		}

		if !filepath.IsAbs(path) {
			return "", errors.E(op, fmt.Errorf("symbolic link is relative (%s): %w", path, err))
		}
	}

	return filepath.Clean(path), nil
}

View on GitHub (pinned to 724551b9ae)

Solutions

1. Check permissions on the directory containing the symlink (needs r+x for the user)
2. ls -l the symlink to confirm it is intact and points where expected; recreate it if corrupted
3. If a package manager was concurrently updating the binary, wait and retry the command
4. Mount/inspect the filesystem if readlink errors persist (overlayfs/NFS quirks)

if fi, err := os.Lstat(p); err == nil && fi.Mode()&os.ModeSymlink != 0 {
    if _, err := os.Readlink(p); err != nil {
        return fmt.Errorf("symlink unreadable before launch: %w", err)
    }
}

func isHealthySymlink(p string) bool {
    fi, err := os.Lstat(p)
    if err != nil || fi.Mode()&os.ModeSymlink == 0 { return false }
    _, err = os.Readlink(p)
    return err == nil
}

if real, err := plugins.Realpath(p); err != nil {
    if strings.Contains(err.Error(), "resolve the symlink") {
        // recreate the symlink / fix parent dir perms, then retry once
    }
}

When it happens

Trigger: os.Readlink(path) erroring after Lstat confirmed ModeSymlink: permission denied reading the link, corrupt/unsupported filesystem, or a race where the link was replaced between Lstat and Readlink.

Common situations: CLI installed behind a symlink in a directory the user cannot search; symlink swapped by a package manager mid-execution; exotic mounts (some network/overlay filesystems) returning errors for readlink.

Related errors

• failed to create a symlink from %q to %q: %w
• failed to remove the symlink in %q: %w
• writing metadata to file: %w
• error getting directory details: %w
• write file: %w

AI-assisted analysis of hasura/graphql-engine@724551b9ae (2026-08-28). Data as JSON: /api/errors/4ffc9d0bbdec217e. Report an issue: GitHub.