AdguardTeam/AdGuardHome · error

target schema version %d lower than current %d

Error message

target schema version %d lower than current %d

What it means

validateVersion rejects a migration where the requested target schema version is lower than the config's current version — i.e. a downgrade. Only forward migrations are supported.

Source

Thrown at internal/configmigrate/migrator.go:96

	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,
	diskConf yobj,
) (err error) {
	upgrades := [LastSchemaVersion]migrateFunc{
		0:  m.migrateTo1,

View on GitHub (pinned to b41aefbe51)

Solutions

1. Pass target >= current (normally LastSchemaVersion)
2. To support an older binary, regenerate a fresh config instead of downgrading
3. Fix argument order if the versions were swapped

Example fix

// before
newBody, _, err := configmigrate.Migrate(ctx, body, 15) // current is 29

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

if target < current { /* don't call Migrate; downgrades unsupported */ }

if err != nil && strings.Contains(err.Error(), "lower than current") { /* fix argument order or accept current version */ }

When it happens

Trigger: Calling Migrate with target < current, e.g. Migrate(body, 15) when the file already has schema_version: 29.

Common situations: Attempting to roll a config back to work with an older tool, accidentally swapping the version arguments, or test code passing the versions in the wrong order.

Related errors

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

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