hasura/graphql-engine · info

no migration

Error message

no migration

What it means

ErrNilVersion is returned by Version() when the database has no version recorded (no migration has been applied yet), analogous to migrate's NilVersion. It distinguishes 'fresh database' from a real error.

Source

Thrown at cli/migrate/migrate.go:44

	"github.com/hasura/graphql-engine/cli/v2/migrate/source"
	"github.com/hasura/graphql-engine/cli/v2/util"
	log "github.com/sirupsen/logrus"
	"golang.org/x/term"
)

// DefaultPrefetchMigrations sets the number of migrations to pre-read
// from the source. This is helpful if the source is remote, but has little
// effect for a local source (i.e. file system).
// Please note that this setting has a major impact on the memory usage,
// since each pre-read migration is buffered in memory. See DefaultBufferSize.
var DefaultPrefetchMigrations = uint64(10)

// DefaultLockTimeout sets the max time a database driver has to acquire a lock.
var DefaultLockTimeout = 15 * time.Second

var (
	ErrNoChange         = errors.New("no change")
	ErrNilVersion       = errors.New("no migration")
	ErrLocked           = errors.New("database locked")
	ErrNoMigrationFiles = errors.New("no migration files found")
	ErrLockTimeout      = errors.New("timeout: can't acquire database lock")
	ErrApplied          = errors.New("Version already applied in database")
	ErrNotApplied       = errors.New("Migration not applied in database")
	ErrNoMigrationMode  = errors.New("Migration mode is disabled")
	ErrMigrationMode    = errors.New("Migration mode is enabled")
)

const (
	applyingMigrationsMessage = "Applying migrations"
)

func newProgressBar(str string, w io.Writer, pbLogs bool) *pb.ProgressBar { //nolint:unparam
	// Default behaviour in non-interactive mode
	if !pbLogs && !term.IsTerminal(int(os.Stdout.Fd())) {
		return nil
	}

View on GitHub (pinned to 724551b9ae)

Solutions

1. Treat it as a fresh database: apply migrations first
2. Verify you're querying the intended environment
3. Use errors.Is(err, migrate.ErrNilVersion) to branch on fresh state

Example fix

// before
v, err := m.Version()
if err != nil { return err }
// after
v, err := m.Version()
if err != nil && !errors.Is(err, migrate.ErrNilVersion) { return err }

func IsFreshDatabase(err error) bool { return errors.Is(err, migrate.ErrNilVersion) }

v, err := m.Version()
if err != nil {
    if errors.Is(err, migrate.ErrNilVersion) { /* fresh DB: apply all */ }
    return err
}

When it happens

Trigger: Calling m.Version() before any migration has ever been applied on the target database.

Common situations: Fresh Hasura project, wrong endpoint/database pointing at an empty instance, or checking version before the first apply.

Related errors

• no change
• version %v not found
• unable to marshal run_sql args in %s: %w
• unable to unmarshal run_sql args in %s: %w
• cannot update from a non-semver version: %s

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