vitessio/vitess · error

unable to perform time_zone conversions from %s to UTC — val

Error message

unable to perform time_zone conversions from %s to UTC — value from DB was: %+v and the result of the attempt was: %s. Either the specified source time zone is invalid or the time zone tables have not been loaded on the %s tablet

What it means

During validation of time_zone conversions for a materialize workflow, the code writes a test datetime to the target and reads it back, expecting the UTC-converted value to parse. If parsing fails, either the configured source time zone is invalid or the MySQL time zone tables are not loaded on the target tablet, so CONVERT_TZ-based timezone conversion cannot work.

Source

Thrown at go/vt/vtctl/workflow/materializer.go:672

// gets elected: in this case user will either see errors during vreplication or vdiff will report mismatches.
func (mz *materializer) checkTZConversion(ctx context.Context, tz string) error {
	err := forAllShards(mz.targetShards, func(target *topo.ShardInfo) error {
		targetPrimary, err := mz.ts.GetTablet(ctx, target.PrimaryAlias)
		if err != nil {
			return vterrors.Wrapf(err, "GetTablet(%v) failed", target.PrimaryAlias)
		}
		testDateTime := "2006-01-02 15:04:05"
		query := fmt.Sprintf("select convert_tz(%s, %s, 'UTC')", encodeString(testDateTime), encodeString(tz))
		qrproto, err := mz.tmc.ExecuteFetchAsApp(ctx, targetPrimary.Tablet, false, &tabletmanagerdatapb.ExecuteFetchAsAppRequest{
			Query:   []byte(query),
			MaxRows: 1,
		})
		if err != nil {
			return vterrors.Wrapf(err, "ExecuteFetchAsApp(%v, %s)", targetPrimary.Tablet, query)
		}
		qr := sqltypes.Proto3ToResult(qrproto)
		if gotDate, err := time.Parse(testDateTime, qr.Rows[0][0].ToString()); err != nil {
			return fmt.Errorf("unable to perform time_zone conversions from %s to UTC — value from DB was: %+v and the result of the attempt was: %s. Either the specified source time zone is invalid or the time zone tables have not been loaded on the %s tablet",
				tz, qr.Rows, gotDate, targetPrimary.Alias)
		}
		return nil
	})
	return err
}

// filterSourceShards filters out source shards that do not overlap with the
// provided target shard. This is an optimization to avoid copying unnecessary
// data between the shards. This optimization is only applied for MoveTables
// when the source and target shard have the same primary vindexes.
func (mz *materializer) filterSourceShards(targetShard *topo.ShardInfo) []*topo.ShardInfo {
	if mz.primaryVindexesDiffer || mz.ms.MaterializationIntent != vtctldatapb.MaterializationIntent_MOVETABLES {
		// Use all source shards.
		return mz.sourceShards
	}
	// Use intersecting source shards.
	var filteredSourceShards []*topo.ShardInfo

View on GitHub (pinned to 01a25a7d17)

Solutions

  1. Load the MySQL time zone tables on the target tablet host: run mysql_tzinfo_to_sql /usr/share/zoneinfo | mysql -u root mysql
  2. Verify the --time-zone value is a valid IANA time zone name and correct any typo
  3. Restart/re-provision the tablet with an image that includes zoneinfo, then retry the workflow

Example fix

// before
MoveTables --time-zone=Ameria/New_York ...
// after
mysql_tzinfo_to_sql /usr/share/zoneinfo | mysql -u root mysql
MoveTables --time-zone=America/New_York ...
Defensive patterns

Strategy: validation

Validate before calling

_, err := time.LoadLocation(tz)
if err != nil {
    return fmt.Errorf("invalid time zone %q: %w", tz, err)
}

Try / catch

if err := createWorkflow(ctx, req); err != nil {
    if strings.Contains(err.Error(), "time_zone conversions") {
        // validate tz name and load mysql timezone tables on tablets
    }
    return err
}

Prevention

When it happens

Trigger: Workflow with TimeZoneConversion enabled executes its validation query against the target primary; the round-tripped value cannot be parsed as the expected datetime format, indicating bad tz config or missing MySQL timezone tables on the tablet.

Common situations: Typo in the --time-zone option (e.g. 'America/New_Yorke'); MySQL time zone tables never loaded on the tablet host (mysql_tzinfo_to_sql not run); container images stripped of /usr/share/zoneinfo.

Related errors

AI-assisted analysis of vitessio/vitess@01a25a7d17 (2026-09-01). Data as JSON: /api/errors/c804e1fcb58200f7. Report an issue: GitHub.