VictoriaMetrics/VictoriaMetrics · error

cannot decode snapshot name %q: %w

Error message

cannot decode snapshot name %q: %w

What it means

storeMetadata derives the backup creation time by parsing the snapshot directory name (filepath.Base(src.Dir)) with snapshotutil.Time. VictoriaMetrics snapshot names look like `<dataDir>/<YYYY-MM-DDTHH-MM-SSZ>-<random>`. If the base directory name does not match that timestamp format, this error is returned.

Source

Thrown at lib/backup/actions/backup.go:91

	}
	if err := runBackup(src, dst, origin, concurrency); err != nil {
		return err
	}
	if err := storeMetadata(src, dst); err != nil {
		return fmt.Errorf("cannot store backup metadata: %w", err)
	}
	if err := dst.CreateFile(backupnames.BackupCompleteFilename, nil); err != nil {
		return fmt.Errorf("cannot create `backup complete` file at %s: %w", dst, err)
	}

	return nil
}

func storeMetadata(src *fslocal.FS, dst common.RemoteFS) error {
	snapshotName := filepath.Base(src.Dir)
	snapshotTime, err := snapshotutil.Time(snapshotName)
	if err != nil {
		return fmt.Errorf("cannot decode snapshot name %q: %w", snapshotName, err)
	}

	d := BackupMetadata{
		CreatedAt:   snapshotTime.Format(time.RFC3339),
		CompletedAt: time.Now().Format(time.RFC3339),
	}

	metadata, err := json.Marshal(d)
	if err != nil {
		return fmt.Errorf("cannot marshal metadata: %w", err)
	}

	if err := dst.CreateFile(backupnames.BackupMetadataFilename, metadata); err != nil {
		return fmt.Errorf("cannot create `backup complete` file at %s: %w", dst, err)
	}

	return nil
}

View on GitHub (pinned to 5079fb58f1)

Solutions

1. Point Src at a real snapshot created via /snapshot/create, e.g. <storageDataPath>/snapshots/2024-01-02T15-04-05Z-<id>.
2. Do not rename the snapshot directory; restore the original `<timestamp>-<random>` name.
3. If you must back up a copy, keep the timestamp prefix format intact so snapshotutil.Time can parse it.
4. Check the wrapped error to see exactly which part of the name failed to decode.

Example fix

// before
src: /var/lib/victoria-metrics-data  // not a snapshot
// after
snapshot=$(curl -XGET 'http://localhost:8428/snapshot/create' | jq -r .status.snapshot)
vmbackup -storageDataPath=/var/lib/victoria-metrics-data -snapshotName=$snapshot -dst=s3://bucket/backup

name := filepath.Base(srcDir)
if _, err := snapshotutil.Time(name); err != nil {
    return fmt.Errorf("src %q is not a VM snapshot dir: %w", srcDir, err)
}

When it happens

Trigger: Backup.Run() with Src pointed at a directory whose basename is not a valid VM snapshot name — e.g. -snapshot.createURL not used and src is a plain directory like /var/lib/victoria-metrics-data or a manually renamed/copied snapshot dir.

Common situations: Pointing vmbackup at the raw storage dir instead of a snapshot; copying a snapshot to a directory with a changed name; running vmbackup for backup of non-snapshot data (explicitly unsupported: the backup works only on /snapshot/create output).

Related errors

• cannot list src parts: %w
• cannot create reader for %s from %s: %w
• unexpected snapshot name=%q; it must match %q regexp
• unexpected timestamp=%q in snapshot name: %w; it must match
• cannot parse partition name %q: %w

AI-assisted analysis of VictoriaMetrics/VictoriaMetrics@5079fb58f1 (2026-09-03). Data as JSON: /api/errors/ab38d0965d965e1f. Report an issue: GitHub.