AdguardTeam/AdGuardHome · error

version.json: bad key %q: %w

Error message

version.json: bad key %q: %w

What it means

Thrown when none of the known download-URL keys are present in version.json. The updater looks for a platform/key combination via downloadURL; if no matching package URL is found, it reports the missing key with errors.ErrNoValue.

Source

Thrown at internal/updater/check.go:120

	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)
	}

	isNewVersion := info.NewVersion != u.version
	if isNewVersion {
		u.logger.InfoContext(
			ctx,
			"a new version is available",
			"current_version", u.version,
			"new_version", info.NewVersion,
		)
	} else {
		u.logger.DebugContext(
			ctx,
			"the current version is up-to-date",
			"current_version", u.version,
		)
	}

View on GitHub (pinned to b41aefbe51)

Solutions

1. Inspect version.json keys and confirm one matches your GOOS/GOARCH package key
2. Upgrade AdGuard Home to a build whose platform is included in the metadata
3. Fix the mirror/pipeline to include all platform keys
4. Use the correct channel URL if pointed at an incomplete one

Example fix

// before
{"version":"v0.107.0","linux_arm64":"https://.../pkg.tar.gz"}
// after
{"version":"v0.107.0","linux_arm64":"https://.../pkg.tar.gz","linux_amd64":"https://.../pkg.tar.gz"}

if _, ok := vj[fmt.Sprintf("%s_%s", runtime.GOOS, goarch)]; !ok {
    // platform key missing; skip update or report unsupported platform
}

if _, err := u.VersionInfo(ctx); err != nil {
    if errors.Is(err, agherrors.ErrNoValue) { /* no package for this platform */ }
}

When it happens

Trigger: VersionInfo on a version.json that lacks the key for the current OS/arch (e.g. 'linux_armv7' or 'windows_amd64') the updater was built for.

Common situations: Running an unsupported or newly-added platform not yet published in channel metadata; typo'd key names in a self-hosted/mirror version.json; checking for a version whose package build failed.

Related errors

• bad value for %q key: %w

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