AdguardTeam/AdGuardHome · error

evaluating executable symlinks: %v

Error message

evaluating executable symlinks: %v

What it means

During the macOS pre-start check, filepath.EvalSymlinks on the executable path failed, so the code can't resolve the real location of the binary to compare against /Applications. Wrapped with %v, so the cause is embedded as text only.

Source

Thrown at internal/aghos/service_darwin.go:24

	"fmt"
	"os"
	"path/filepath"
	"strings"

	"github.com/AdguardTeam/golibs/log"
)

// preCheckActionStart performs the service start action pre-check.  It warns
// user that the service should be installed into Applications directory.
func preCheckActionStart() (err error) {
	exe, err := os.Executable()
	if err != nil {
		return fmt.Errorf("getting executable path: %v", err)
	}

	exe, err = filepath.EvalSymlinks(exe)
	if err != nil {
		return fmt.Errorf("evaluating executable symlinks: %v", err)
	}

	if !strings.HasPrefix(exe, "/Applications/") {
		log.Info("warning: service must be started from within the /Applications directory")
	}

	return err
}

View on GitHub (pinned to b41aefbe51)

Solutions

1. Point your launcher at the real binary inside /Applications/AdGuardHome.app (or copy it there)
2. Remove or fix dangling symlinks in the launch path: ls -l to inspect each component
3. Clear quarantine attributes if Gatekeeper translocation is involved: xattr -dr com.apple.quarantine /Applications/AdGuardHome.app

exe, err := os.Executable()
if err == nil {
    if _, err := filepath.EvalSymlinks(exe); err != nil { /* fix symlinks before starting */ }
}

When it happens

Trigger: Starting the service on macOS when the executable path contains a symlink whose target no longer exists, or a path component is unreadable/permission-denied, causing EvalSymlinks to error (e.g. ENOENT on a dangling symlink).

Common situations: Launching via a symlink in ~/bin pointing to a moved/deleted AdGuardHome.app; translocated/quarantined app bundles; permission-restricted directories in the path.

Related errors

• getting executable path: %v

AI-assisted analysis of AdguardTeam/AdGuardHome@b41aefbe51 (2026-08-27). Data as JSON: /api/errors/eb9cc7d0b4f8ce1d. Report an issue: GitHub.