multica-ai/multica · error

check migration %q: %w

Error message

check migration %q: %w

What it means

The per-version EXISTS check against schema_migrations failed while scanning. This lookup decides skip-vs-apply for each migration file, so any error aborts the loop before anything is applied for that version. Causes: connection loss, cancelled context, the tracking table being dropped/renamed mid-run by another session, or permissions on it.

Source

Thrown at server/cmd/migrate/main.go:407

	if _, err := conn.Exec(ctx, fmt.Sprintf(`
		CREATE TABLE IF NOT EXISTS %s (
			version TEXT PRIMARY KEY,
			applied_at TIMESTAMPTZ NOT NULL DEFAULT now()
		)
	`, tableIdent)); err != nil {
		return fmt.Errorf("create migrations table: %w", err)
	}

	existsSQL := fmt.Sprintf("SELECT EXISTS(SELECT 1 FROM %s WHERE version = $1)", tableIdent)
	insertSQL := fmt.Sprintf("INSERT INTO %s (version) VALUES ($1)", tableIdent)
	deleteSQL := fmt.Sprintf("DELETE FROM %s WHERE version = $1", tableIdent)

	for _, file := range opts.Files {
		version := migrations.ExtractVersion(file)

		var exists bool
		if err := conn.QueryRow(ctx, existsSQL, version).Scan(&exists); err != nil {
			return fmt.Errorf("check migration %q: %w", version, err)
		}

		if opts.Direction == "up" {
			if exists {
				fmt.Printf("  skip  %s (already applied)\n", version)
				continue
			}
		} else {
			if !exists {
				fmt.Printf("  skip  %s (not applied)\n", version)
				continue
			}
		}

		sql, err := os.ReadFile(file)
		if err != nil {
			return fmt.Errorf("read migration %q: %w", file, err)
		}

View on GitHub (pinned to 2c0912b6ec)

Solutions

1. Re-run `migrate up`; applied versions are skipped via the same EXISTS check
2. Do not manually edit/drop schema_migrations while migrations run — investigate drift with SELECT * FROM schema_migrations ORDER BY version
3. Grant SELECT on the tracking table to the migration role if permission-denied

if err := conn.QueryRow(ctx, existsSQL, version).Scan(&exists); err != nil {
    return fmt.Errorf("check migration %q: %w", version, err)
}

When it happens

Trigger: Someone drops or truncates schema_migrations while the run is in progress; ctx cancelled; network interruption; SELECT privilege revoked on the tracking table.

Common situations: Rare; most often an operator manually messing with schema_migrations during a run, or a flaky connection in long migration sequences.

Related errors

• apply migration %q: %w
• scan task_usage time range: %w
• stamp watermark: %w
• inspect concurrent index %q: %w
• relation %q exists but is not an index

AI-assisted analysis of multica-ai/multica@2c0912b6ec (2026-08-15). Data as JSON: /api/errors/b2b98358796325a5. Report an issue: GitHub.