hasura/graphql-engine · error

unable to unmarshal run_sql args in %s: %w

Error message

unable to unmarshal run_sql args in %s: %w

What it means

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.

Source

Thrown at cli/commands/scripts_update_config_v2.go:173

						argByt, err := yaml.Marshal(query.Args)
						if err != nil {
							return errors.E(
								op,
								fmt.Errorf(
									"unable to marshal run_sql args in %s: %w",
									upMetaMigration.Raw,
									err,
								),
							)
						}

						var to hasura.PGRunSQLInput

						err = yaml.Unmarshal(argByt, &to)
						if err != nil {
							return errors.E(
								op,
								fmt.Errorf(
									"unable to unmarshal run_sql args in %s: %w",
									upMetaMigration.Raw,
									err,
								),
							)
						}

						sqlUp.WriteString("\n")
						sqlUp.WriteString(to.SQL)
					}
				}
				// check if up.sql file exists
				if sqlUp.String() != "" {
					upMigration, ok := fileCfg.Migrations.Migrations[version][source.Up]
					if !ok {
						// if up.sql doesn't exists, create a up.sql file and upMigration
						var filePath string

View on GitHub (pinned to 724551b9ae)

Solutions

1. Open the up.yaml file named in the error and check the run_sql args block has the form `args: {sql: "..."}`
2. Fix or delete the malformed query, restore from migrations_backup if needed, and re-run update-project-v2

Example fix

# before (in 123.up.yaml)
- type: run_sql
  args:
    sq: "select 1"
# after
- type: run_sql
  args:
    sql: "select 1"

// verify each run_sql args block decodes into PGRunSQLInput shape
var to struct{ SQL string `yaml:"sql"` }
if err := yaml.Unmarshal(argByt, &to); err != nil {
  log.Printf("bad run_sql args in %s: %v", file, err)
}
if to.SQL == "" { log.Printf("run_sql args missing sql key in %s", file) }

func isValidRunSQLArgs(v any) bool {
  m, ok := v.(map[string]any)
  if !ok { return false }
  sql, ok := m["sql"].(string)
  return ok && sql != ""
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• unable to marshal run_sql args in %s: %w
• error in unmarshal to common: %w
• error serving console: %w
• operation failed: %w
• unable to create directory: %w

AI-assisted analysis of hasura/graphql-engine@724551b9ae (2026-08-28). Data as JSON: /api/errors/c55442453e44f572. Report an issue: GitHub.