AdguardTeam/AdGuardHome · error

preparing: %w

Error message

preparing: %w

What it means

Wraps any failure of the preparation step of the self-update flow: computing the update directory, validating the package URL, and stat-ing the current executable. The underlying error tells which sub-check failed.

Source

Thrown at internal/updater/updater.go:169

		mu: &sync.RWMutex{},
	}
}

// Update performs the auto-update.  It returns an error if the update fails.
// If firstRun is true, it assumes the configuration file doesn't exist.
func (u *Updater) Update(ctx context.Context, firstRun bool) (err error) {
	u.mu.Lock()
	defer u.mu.Unlock()

	u.logger.InfoContext(ctx, "starting update", "first_run", firstRun)
	defer func() {
		u.logUpdateResult(ctx, err)
	}()

	err = u.prepare(ctx)
	if err != nil {
		return fmt.Errorf("preparing: %w", err)
	}

	defer u.clean(ctx)

	err = u.downloadPackageFile(ctx)
	if err != nil {
		return fmt.Errorf("downloading package file: %w", err)
	}

	err = u.unpack(ctx)
	if err != nil {
		return fmt.Errorf("unpacking: %w", err)
	}

	if !firstRun {
		err = u.check(ctx)
		if err != nil {
			return fmt.Errorf("checking config: %w", err)

View on GitHub (pinned to b41aefbe51)

Solutions

1. Check the wrapped error to see if it's 'invalid PackageURL' or 'checking %q'
2. Verify the current executable exists and the process has permission to stat it
3. Ensure packageURL points to a real file name, not a directory
4. Fix or recreate the configured binary path/workDir

Example fix

// before
u.packageURL = "https://example.com/dl/"
// after
u.packageURL = "https://example.com/dl/AdGuardHome_linux_amd64.tar.gz"

if _, base := filepath.Split(u.packageURL); base == "" { /* fix URL first */ }
if _, err := os.Stat(u.execPath); err != nil { /* fix exec path first */ }

if err := u.Update(ctx); err != nil {
    if strings.HasPrefix(err.Error(), "preparing:") { /* inspect wrapped cause: URL or stat */ }
}

When it happens

Trigger: Calling Updater.Update with a packageURL whose path basename is empty, or when os.Stat on the current executable path fails (moved/deleted binary, wrong exec path config).

Common situations: Running from a deleted or replaced binary; misconfigured workDir/exec path; package URL ending in '/' so filepath.Split yields an empty filename.

Related errors

• networksetup failed to configure dns servers: %w
• watching %s %s: %w
• reading cert file: %w
• reading key file: %w
• reading db: %w

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