{"record":{"id":"c55442453e44f572","repo":"hasura/graphql-engine","slug":"unable-to-unmarshal-run-sql-args-in-s-w","errorCode":null,"errorMessage":"unable to unmarshal run_sql args in %s: %w","messagePattern":"unable to unmarshal run_sql args in (.+?): %w","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/commands/scripts_update_config_v2.go","lineNumber":173,"sourceCode":"\t\t\t\t\t\targByt, err := yaml.Marshal(query.Args)\n\t\t\t\t\t\tif err != nil {\n\t\t\t\t\t\t\treturn errors.E(\n\t\t\t\t\t\t\t\top,\n\t\t\t\t\t\t\t\tfmt.Errorf(\n\t\t\t\t\t\t\t\t\t\"unable to marshal run_sql args in %s: %w\",\n\t\t\t\t\t\t\t\t\tupMetaMigration.Raw,\n\t\t\t\t\t\t\t\t\terr,\n\t\t\t\t\t\t\t\t),\n\t\t\t\t\t\t\t)\n\t\t\t\t\t\t}\n\n\t\t\t\t\t\tvar to hasura.PGRunSQLInput\n\n\t\t\t\t\t\terr = yaml.Unmarshal(argByt, &to)\n\t\t\t\t\t\tif err != nil {\n\t\t\t\t\t\t\treturn errors.E(\n\t\t\t\t\t\t\t\top,\n\t\t\t\t\t\t\t\tfmt.Errorf(\n\t\t\t\t\t\t\t\t\t\"unable to unmarshal run_sql args in %s: %w\",\n\t\t\t\t\t\t\t\t\tupMetaMigration.Raw,\n\t\t\t\t\t\t\t\t\terr,\n\t\t\t\t\t\t\t\t),\n\t\t\t\t\t\t\t)\n\t\t\t\t\t\t}\n\n\t\t\t\t\t\tsqlUp.WriteString(\"\\n\")\n\t\t\t\t\t\tsqlUp.WriteString(to.SQL)\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t\t// check if up.sql file exists\n\t\t\t\tif sqlUp.String() != \"\" {\n\t\t\t\t\tupMigration, ok := fileCfg.Migrations.Migrations[version][source.Up]\n\t\t\t\t\tif !ok {\n\t\t\t\t\t\t// if up.sql doesn't exists, create a up.sql file and upMigration\n\t\t\t\t\t\tvar filePath string\n","sourceCodeStart":155,"sourceCodeEnd":191,"githubUrl":"https://github.com/hasura/graphql-engine/blob/724551b9ae87845594ef0408cff0e50eb6c90dc5/cli/commands/scripts_update_config_v2.go#L155-L191","documentation":"During update-project-v2, after marshaling run_sql args the script unmarshals them into hasura.PGRunSQLInput (a struct with a SQL string field). If the args do not match that shape (e.g. missing sql key, wrong types, duplicate keys), yaml.Unmarshal fails and this error is returned with the migration filename.","triggerScenarios":"A <version>.up.yaml run_sql query whose args are not a valid PGRunSQLInput: no `sql` string field, a non-string `sql`, or extra data that breaks strict decoding.","commonSituations":"Typos in hand-written migrations (e.g. `sql:` misspelled), args written as a scalar instead of a mapping, or metadata exported by mismatched CLI/server versions.","solutions":["Open the up.yaml file named in the error and check the run_sql args block has the form `args: {sql: \"...\"}`","Fix or delete the malformed query, restore from migrations_backup if needed, and re-run update-project-v2"],"exampleFix":"# before (in 123.up.yaml)\n- type: run_sql\n  args:\n    sq: \"select 1\"\n# after\n- type: run_sql\n  args:\n    sql: \"select 1\"","handlingStrategy":"validation","validationCode":"// verify each run_sql args block decodes into PGRunSQLInput shape\nvar to struct{ SQL string `yaml:\"sql\"` }\nif err := yaml.Unmarshal(argByt, &to); err != nil {\n  log.Printf(\"bad run_sql args in %s: %v\", file, err)\n}\nif to.SQL == \"\" { log.Printf(\"run_sql args missing sql key in %s\", file) }","typeGuard":"func isValidRunSQLArgs(v any) bool {\n  m, ok := v.(map[string]any)\n  if !ok { return false }\n  sql, ok := m[\"sql\"].(string)\n  return ok && sql != \"\"\n}","tryCatchPattern":null,"preventionTips":["Use `args: {sql: \"...\"}` as the only shape for run_sql in migrations","Lint migrations in CI with a YAML schema check before running the conversion script"],"tags":["hasura","cli","yaml","migration","unmarshal","run-sql"],"backgroundTag":"yaml-unmarshal-type-mismatch","analyzedSha":"724551b9ae87845594ef0408cff0e50eb6c90dc5","analyzedAt":"2026-08-28T07:32:55.105Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}