AdguardTeam/AdGuardHome · error

version.json: %w

Error message

version.json: %w

What it means

The downloaded version.json body failed to parse as the expected JSON object of string values; the json.Unmarshal error is wrapped as 'version.json: %w'.

Source

Thrown at internal/updater/check.go:104

}

// parseVersionResponse parses version-related data and unmarshals it into the
// [VersionInfo] structure.
func (u *Updater) parseVersionResponse(
	ctx context.Context,
	data []byte,
) (vi VersionInfo, err error) {
	info := VersionInfo{
		CanAutoUpdate: aghalg.NBFalse,
	}
	versionJSON := map[string]string{
		"version":          "",
		"announcement":     "",
		"announcement_url": "",
	}
	err = json.Unmarshal(data, &versionJSON)
	if err != nil {
		return info, fmt.Errorf("version.json: %w", err)
	}

	for k, v := range versionJSON {
		err = validate.NotEmpty("version_json_value", v)
		if err != nil {
			return info, fmt.Errorf("bad value for %q key: %w", k, err)
		}
	}

	info.NewVersion = versionJSON["version"]
	info.Announcement = versionJSON["announcement"]
	info.AnnouncementURL = versionJSON["announcement_url"]

	packageURL, key, found := u.downloadURL(ctx, versionJSON)
	if !found {
		return info, fmt.Errorf("version.json: bad key %q: %w", key, errors.ErrNoValue)
	}

View on GitHub (pinned to b41aefbe51)

Solutions

1. Fetch the URL with curl and validate the JSON shape (flat object of strings)
2. Fix the hosted version.json to the expected format
3. If a redirect serves wrong content, correct the URL to the final endpoint

Example fix

// before (served)
{"version": 1.2}
// after
{"version": "v1.2.0", "announcement": "", "announcement_url": ""}

var probe map[string]string
if err := json.Unmarshal(body, &probe); err != nil { return fmt.Errorf("version.json not a flat string map") }

func isVersionJSON(b []byte) bool { var m map[string]string; return json.Unmarshal(b, &m) == nil }

info, err := u.VersionInfo(ctx)
if err != nil && strings.Contains(err.Error(), "version.json") { /* endpoint serving wrong content; alert ops */ }

When it happens

Trigger: VersionInfo receiving a body that is not valid JSON or does not match map[string]string semantics (numbers, nested objects), e.g. an HTML error page served with 200.

Common situations: Update server misconfigured to serve HTML/markdown, a redirected login page, or a newer schema with non-string fields.

Related errors

• parsing json time: %w
• interface %s has no ipv4 addresses
• found no dns servers in %s
• parsing certificate at index %d: %w
• parsing private key: %w

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