gastownhall/beads · warning

dolt_stats_gc: %w

Error message

dolt_stats_gc: %w

What it means

After DoltGC succeeds, runShutdownGC executes CALL DOLT_STATS_GC() on the same connection to garbage-collect Dolt statistics tables. This error wraps the SQL failure from that stored-procedure call.

Source

Thrown at internal/storage/dbproxy/server/doltserver.go:407

		return nil
	}
	db, err := sql.Open("mysql", s.DSN(ctx, s.database, "root", ""))
	if err != nil {
		return fmt.Errorf("open gc connection: %w", err)
	}
	defer func() { retErr = errors.Join(retErr, db.Close()) }()

	conn, err := db.Conn(ctx)
	if err != nil {
		return fmt.Errorf("acquire gc connection: %w", err)
	}
	defer func() { retErr = errors.Join(retErr, conn.Close()) }()

	if err := versioncontrolops.DoltGC(ctx, conn); err != nil {
		retErr = errors.Join(retErr, err)
	}
	if _, err := conn.ExecContext(ctx, "CALL DOLT_STATS_GC()"); err != nil {
		retErr = errors.Join(retErr, fmt.Errorf("dolt_stats_gc: %w", err))
	}
	return retErr
}

func (s *DoltServer) Running(_ context.Context) bool {
	if s.egCtx == nil {
		return false
	}
	return s.egCtx.Err() == nil
}

func (s *DoltServer) Dial(ctx context.Context) (net.Conn, error) {
	network, addr := "tcp", net.JoinHostPort(s.config.Host(), strconv.Itoa(s.config.Port()))
	if sock := s.config.Socket(); sock != "" {
		network, addr = "unix", sock
	}
	var d net.Dialer
	conn, err := d.DialContext(ctx, network, addr)

View on GitHub (pinned to 71377f2769)

Solutions

1. Upgrade the Dolt server binary to a version that provides DOLT_STATS_GC()
2. Verify with `CALL DOLT_STATS_GC();` in a dolt sql shell against the same database
3. Increase shutdown timeout so the procedure can complete on large databases
4. If the joined Stop error contains only dolt_stats_gc and data is intact, treat as non-fatal but file/upgrade — GC hygiene is degraded

Example fix

null

// detect capability before relying on stats GC
conn.QueryContext(ctx, "SELECT 1 FROM information_schema.routines WHERE routine_name='DOLT_STATS_GC'") // if empty, server is too old

if err := server.Stop(ctx); err != nil {
    if strings.Contains(err.Error(), "dolt_stats_gc") {
        log.Warn("stats GC failed (old Dolt version?); core GC result unaffected", "err", err)
        err = nil
    }
    return err
}

When it happens

Trigger: Stop triggers shutdown GC; DOLT_STATS_GC() fails because the dolt_stats schema/procedure is missing (older Dolt server version), the stats subsystem is disabled, the connection died mid-call, or the context was cancelled.

Common situations: Running against an external/older dolt sql-server that predates DOLT_STATS_GC; stats tables corrupted; shutdown timeout elapsing while the procedure runs on a large database.

Related errors

• open gc connection: %w
• dolt directory is required
• dolt binary not found
• dolt path is not executable
• dolt version probe failed

AI-assisted analysis of gastownhall/beads@71377f2769 (2026-08-30). Data as JSON: /api/errors/1ddfbfc3ee608128. Report an issue: GitHub.