What causes "getting list of migrations to move: %w" in hasura/graphql-engine?

Run the command from the project root that contains the migrations/ directory

getting list of migrations to move: %w

Error message

getting list of migrations to move: %w

What it means

Thrown by scripts.UpdateProjectV3 when getMigrationDirectoryNames fails while listing the existing flat migrations/ directory that needs restructuring into migrations/<database>/. The %w wraps a filesystem error — typically the migrations directory doesn't exist or isn't readable.

Source

Thrown at cli/internal/scripts/update-project-v3.go:161

		if opts.MoveStateOnly {
			opts.EC.Logger.Debug("move state only is set, copied state and returning early")

			return nil
		}

		opts.EC.Logger.Debug("completed: copying state from hdb_catalog.schema_migrations")
	}

	opts.EC.Logger.Debug("start: copy old migrations to new directory structure")
	opts.EC.Spin("Moving migrations and seeds to new directories ")
	// move migration child directories
	// get directory names to move
	migrationDirectoriesToMove, err := getMigrationDirectoryNames(
		opts.Fs,
		opts.MigrationsAbsDirectoryPath,
	)
	if err != nil {
		return errors.E(op, fmt.Errorf("getting list of migrations to move: %w", err))
	}
	// move seed child directories
	// get directory names to move
	seedFilesToMove, err := getSeedFiles(opts.Fs, opts.SeedsAbsDirectoryPath)
	if err != nil {
		return errors.E(op, fmt.Errorf("getting list of seed files to move: %w", err))
	}

	// create a new directory for TargetDatabase
	targetMigrationsDirectoryName := filepath.Join(opts.MigrationsAbsDirectoryPath, targetDatabase)
	if err = opts.Fs.Mkdir(targetMigrationsDirectoryName, 0o755); err != nil {
		return errors.E(op, fmt.Errorf("creating target migrations directory: %w", err))
	}

	// create a new directory for TargetDatabase
	targetSeedsDirectoryName := filepath.Join(opts.SeedsAbsDirectoryPath, targetDatabase)
	if err = opts.Fs.Mkdir(targetSeedsDirectoryName, 0o755); err != nil {
		return errors.E(op, fmt.Errorf("creating target seeds directory: %w", err))

View on GitHub (pinned to 724551b9ae)

Solutions

Run the command from the project root that contains the migrations/ directory
If migrations/ was deleted or never existed, create it (mkdir migrations) or restore it from git
Fix read permissions on the directory if the process cannot list it

Example fix

# before: running from wrong dir
cd / && hasura scripts update-project-v3  # -> getting list of migrations to move: ...

# after:
cd my-hasura-project && hasura scripts update-project-v3

Defensive patterns

Strategy: validation

Validate before calling

if info, err := os.Stat(migrationsDir); err != nil || !info.IsDir() {
	return fmt.Errorf("migrations directory %s missing or not a directory", migrationsDir)
}

Prevention

Run CLI commands from the project root
Ensure migrations/ exists in the repo (add a placeholder migration if needed)

When it happens

Trigger: Running update-project-v3 when the project's migrations directory is missing, unreadable, or is not a directory (e.g. a file named migrations), or the filesystem errors during ReadDir.

Common situations: Running the upgrade from the wrong working directory (no migrations/ folder present), permissions issues on the directory, or a repo cloned without the migrations folder.

Related errors

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