hasura/graphql-engine · error

invalid yaml file: %s: %w

Error message

invalid yaml file: %s: %w

What it means

Produced by IsEmptyFile when a migration marked as YAML (direction MetaUp/MetaDown, i.e. a .yaml migration) fails to unmarshal as a YAML list. The CLI expects YAML migrations to decode into []any; malformed YAML (tabs, bad indentation, scalar at top level) makes yaml.Unmarshal fail and the scan aborts.

Source

Thrown at cli/migrate/source/parse.go:134

	return nil, errors.E(op, ErrParse)
}

// Validate file to check for empty sql or yaml content.
func IsEmptyFile(m *Migration, directory string) (bool, error) {
	var op errors.Op = "source.IsEmptyFile"

	data, err := os.ReadFile(filepath.Join(directory, m.Raw))
	if err != nil {
		return false, errors.E(op, fmt.Errorf("cannot read file %s: %w", m.Raw, err))
	}

	switch direction := m.Direction; direction {
	case MetaUp, MetaDown:
		var t []any

		err = yaml.Unmarshal(data, &t)
		if err != nil {
			return false, errors.E(op, fmt.Errorf("invalid yaml file: %s: %w", m.Raw, err))
		}

		if len(t) == 0 {
			return false, nil
		}
	case Up, Down:
		if string(data) == "" {
			return false, nil
		}
	}

	return true, nil
}

View on GitHub (pinned to 724551b9ae)

Solutions

1. Validate the offending file with a YAML linter or `yamllint migrations/<file>`
2. Ensure the top level is a list of actions, each item like `- type: run_sql\n args: ...`
3. Replace tabs with spaces and fix indentation
4. If the migration was meant to be SQL, use a .sql extension instead

Example fix

# before (migrations/05_seed.up.yaml)
version: 2   # mapping, not a list -> invalid yaml file

# after
- type: run_sql
  args:
    sql: SELECT 1;

// Validate a YAML migration parses as a list before scanning
var t []any
if err := yaml.Unmarshal(raw, &t); err != nil {
    return fmt.Errorf("migration %s is not a YAML list: %w", name, err)
}

if _, err := source.IsEmptyFile(m, dir); err != nil {
    if strings.Contains(err.Error(), "invalid yaml file") {
        // yamllint the file; fix tabs/structure
    }
}

When it happens

Trigger: Any migrations/*.up.yaml or *.down.yaml file that is not valid YAML or not a top-level sequence — e.g. a mapping {key: value}, a bare scalar, tab indentation, or truncated content. Hit on any migrate command that scans the source (apply, status, create validation).

Common situations: Hand-editing YAML migrations with tabs (illegal in YAML); pasting SQL into a .yaml file; converting .sql migrations to .yaml without wrapping statements in a list (`- args: ...`); merge conflicts left in the file.

Related errors

• operation failed: %w
• cannot write migration directory: %w
• applying migrations on source: %s: %w
• operation failed: %w
• error while deleting status for database '%s': %w

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