AdguardTeam/AdGuardHome · error

unknown current schema version %d

Error message

unknown current schema version %d

What it means

validateVersion rejects the migration because the config's current schema_version is greater than the target version being migrated to. In practice current > target combined with target ≤ LastSchemaVersion means the file claims a version this build doesn't know or a downgrade was attempted.

Source

Thrown at internal/configmigrate/migrator.go:92

		return body, false, err
	}

	buf := bytes.NewBuffer(newBody)
	enc := yaml.NewEncoder(buf)
	enc.SetIndent(2)

	if err = enc.Encode(diskConf); err != nil {
		return body, false, fmt.Errorf("generating new config: %w", err)
	}

	return buf.Bytes(), true, nil
}

// validateVersion validates the current and desired schema versions.
func validateVersion(current, target uint) (err error) {
	switch {
	case current > target:
		return fmt.Errorf("unknown current schema version %d", current)
	case target > LastSchemaVersion:
		return fmt.Errorf("unknown target schema version %d", target)
	case target < current:
		return fmt.Errorf("target schema version %d lower than current %d", target, current)
	default:
		return nil
	}
}

// migrateFunc is a function that upgrades a config and returns an error.
type migrateFunc = func(ctx context.Context, diskConf yobj) (err error)

// upgradeConfigSchema upgrades the configuration schema in diskConf from
// current to target version.  current must be less than target, and both must
// be non-negative and less or equal to [LastSchemaVersion].
func (m *Migrator) upgradeConfigSchema(
	ctx context.Context,
	current, target uint,

View on GitHub (pinned to b41aefbe51)

Solutions

1. If the config came from a newer release, restore the matching (or newer) binary; old builds cannot downgrade configs
2. Regenerate the config from scratch (the old body is returned on failure, so nothing is lost)
3. Pass target = LastSchemaVersion supported by your build

Example fix

// before
newBody, ok, err := configmigrate.Migrate(ctx, body, 20) // config is v29

// after
newBody, ok, err := configmigrate.Migrate(ctx, body, configmigrate.LastSchemaVersion)

ver, _, _ := fieldVal[int](diskConf, "schema_version")
if uint(ver) > target { /* refuse: downgrade not supported; use newer binary */ }

if _, _, err := configmigrate.Migrate(ctx, body, target); err != nil && strings.Contains(err.Error(), "unknown current schema version") { /* restore matching binary version or fresh config */ }

When it happens

Trigger: Calling Migrate on a config whose schema_version exceeds the requested target (e.g. running an older binary against a config written by a newer release, or explicitly passing a low target).

Common situations: Rolling back AdGuard Home to an older version while keeping a newer config file, or pinning an older target schema version.

Related errors

• unknown target schema version %d
• target schema version %d lower than current %d
• migrating schema %d to %d: %w
• parsing config file for upgrade: %w
• generating new config: %w

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