{"record":{"id":"99d8d64e15f6087a","repo":"multica-ai/multica","slug":"apply-migration-q-w","errorCode":null,"errorMessage":"apply migration %q: %w","messagePattern":"apply migration %q: %w","errorType":"console","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"server/cmd/migrate/main.go","lineNumber":441,"sourceCode":"\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"read migration %q: %w\", file, err)\n\t\t}\n\n\t\t// Run any pre-migration hook before the SQL file. Hooks\n\t\t// receive the *pgxpool.Pool (not the loop's pinned conn), so\n\t\t// they can acquire other session-level locks without\n\t\t// colliding with migrationAdvisoryLockKey. Hook failures\n\t\t// abort the run before schema_migrations is updated, so the\n\t\t// same version retries cleanly on the next invocation.\n\t\tif hook, ok := opts.Hooks[version]; ok && hook != nil {\n\t\t\tslog.Info(\"running pre-migration hook\", \"version\", version, \"direction\", opts.Direction)\n\t\t\tif err := hook(ctx, pool); err != nil {\n\t\t\t\treturn fmt.Errorf(\"pre-migration hook for %q (%s): %w\", version, opts.Direction, err)\n\t\t\t}\n\t\t}\n\n\t\tif _, err := conn.Exec(ctx, string(sql)); err != nil {\n\t\t\treturn fmt.Errorf(\"apply migration %q: %w\", file, err)\n\t\t}\n\n\t\tif opts.Direction == \"up\" {\n\t\t\t_, err = conn.Exec(ctx, insertSQL, version)\n\t\t} else {\n\t\t\t_, err = conn.Exec(ctx, deleteSQL, version)\n\t\t}\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"record migration %q: %w\", version, err)\n\t\t}\n\n\t\tfmt.Printf(\"  %s  %s\\n\", opts.Direction, version)\n\t}\n\n\treturn nil\n}\n\n// quoteQualifiedIdentifier safely quotes either an unqualified table","sourceCodeStart":423,"sourceCodeEnd":459,"githubUrl":"https://github.com/multica-ai/multica/blob/2c0912b6ec764b373d44eeea1e80f0d9f11ab417/server/cmd/migrate/main.go#L423-L459","documentation":"Returned when conn.Exec of the migration SQL file itself fails while applying it. The migration runs on the loop's pinned connection holding the migration advisory lock, so a failure means the SQL in the .sql file was rejected by Postgres (syntax, dependency, permission, or existing object).","triggerScenarios":"Applying a migration file whose SQL fails: CREATE TABLE on an existing name, invalid syntax, reference to a column/table created in a later migration, insufficient privileges, or a statement cancelled by statement_timeout.","commonSituations":"Editing an already-applied migration file (checksum/content drift so it no longer matches the schema), splitting one migration into two and running them out of order, running migrations with a role that lacks CREATE privilege, or a concurrent process having created the same object.","solutions":["Read the wrapped Postgres error in the %w chain — it names the exact statement-level failure (relation already exists, syntax error, etc.).","If the object already exists because the migration partially applied in a prior failed run, wrap destructive/creative statements in IF (NOT) EXISTS or roll back the partial objects by hand, then re-run.","If this is an edited already-recorded migration, restore the original file or write a NEW migration instead — never edit an applied version.","Re-run `migrate`; schema_migrations was not updated for this version, so it retries."],"exampleFix":"-- before: fails on re-run after a partial failure\nCREATE TABLE issue_links (...);\n\n-- after: idempotent so a clean retry succeeds\nCREATE TABLE IF NOT EXISTS issue_links (...);","handlingStrategy":"validation","validationCode":"-- Dry-run each new migration on a schema snapshot (e.g. via a CI step that\n-- clones prod schema and applies pending files) before it reaches production,\n-- so apply failures surface in CI, not during deploy.","typeGuard":null,"tryCatchPattern":"err := runMigrations(ctx, pool, opts)\nif err != nil {\n    var pgErr *pgconn.PgError\n    if errors.As(err, &pgErr) {\n        switch pgErr.Code {\n        case \"42P07\", \"42710\": // duplicate_table, duplicate_object\n            log.Printf(\"object already exists; migration may have partially applied: %v\", pgErr.Message)\n        case \"42703\", \"42P01\": // undefined column/table\n            log.Printf(\"ordering problem: references an object created later: %v\", pgErr.Message)\n        }\n    }\n    return err\n}","preventionTips":["Never edit an already-applied migration; always add a new file.","Prefer IF NOT EXISTS / IF EXISTS in DDL so retries after partial failures succeed.","Run pending migrations against a prod-schema clone in CI before deploy."],"tags":["go","database","migration","postgres","sql"],"backgroundTag":null,"analyzedSha":"2c0912b6ec764b373d44eeea1e80f0d9f11ab417","analyzedAt":"2026-08-15T13:25:18.241Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}