AdguardTeam/AdGuardHome · error

migrating schema %d to %d: %w

Error message

migrating schema %d to %d: %w

What it means

upgradeConfigSchema reports that an individual step migration (from schema cur to cur+1) failed, wrapping the step's error. The chain identifies exactly which schema transition broke and why.

Source

Thrown at internal/configmigrate/migrator.go:157

		25: m.migrateTo26,
		26: m.migrateTo27,
		27: m.migrateTo28,
		28: m.migrateTo29,
		29: m.migrateTo30,
		30: m.migrateTo31,
		31: m.migrateTo32,
		32: m.migrateTo33,
		33: m.migrateTo34,
	}

	for i, migrate := range upgrades[current:target] {
		cur := current + uint(i)
		next := current + uint(i) + 1

		m.logger.InfoContext(ctx, "upgrade yaml", "from", cur, "to", next)

		if err = migrate(ctx, diskConf); err != nil {
			return fmt.Errorf("migrating schema %d to %d: %w", cur, next, err)
		}
	}

	return nil
}

View on GitHub (pinned to b41aefbe51)

Solutions

1. Read the wrapped cause; the "from"/"to" versions in the message tell you which migration step to inspect
2. Check the field mentioned by the inner error and correct its type/value in the config
3. Look at internal/configmigrate/v<from+1>.go to see exactly what shape that step expects

null // validate config shape per-step is impractical generically; pre-validate the specific field types your config uses (upstreams as strings, clients as objects, bind_host as IP)

if _, _, err := configmigrate.Migrate(ctx, body, target); err != nil && strings.Contains(err.Error(), "migrating schema") { /* parse cur/next from message, inspect configmigrate/v<next>.go, fix field, retry */ }

When it happens

Trigger: Calling Migrate where one of the per-version migration functions fails, e.g. addQUICPorts hitting a non-string upstream field (v10), an invalid bind_host (v23), or a malformed filters entry (v29).

Common situations: Configs hand-edited so a field has an unexpected type (a list where a string was expected), or partially corrupted files that still parse as YAML but have the wrong shape for a specific migration step.

Related errors

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

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