AdguardTeam/AdGuardHome · error

unknown target schema version %d

Error message

unknown target schema version %d

What it means

validateVersion rejects the requested target schema version because it is higher than LastSchemaVersion known to this build. The library refuses to write a schema version it has no migrations for.

Source

Thrown at internal/configmigrate/migrator.go:94

	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,
	diskConf yobj,
) (err error) {

View on GitHub (pinned to b41aefbe51)

Solutions

1. Use configmigrate.LastSchemaVersion as the target instead of a literal number
2. Upgrade the module/binary to a version whose LastSchemaVersion covers the desired target

Example fix

// before
_, _, err := configmigrate.Migrate(ctx, body, 99)

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

if target > configmigrate.LastSchemaVersion { target = configmigrate.LastSchemaVersion }

if err != nil && strings.Contains(err.Error(), "unknown target schema version") { /* retry with LastSchemaVersion */ }

When it happens

Trigger: Calling Migrate with a target greater than LastSchemaVersion, e.g. hardcoding a future version number or mixing builds with different configmigrate packages.

Common situations: Hardcoded target versions in deployment scripts that outlive a binary upgrade; using constants from a newer module version than the compiled binary.

Related errors

• unknown current 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/eaa55b9130576f5f. Report an issue: GitHub.