dgraph-io/dgraph · error

mapper.Map

Error message

mapper.Map

What it means

RunMapper wraps any error returned by mapper.Map — the streaming step that reads the backup and writes Dgraph-format map files to disk — with 'mapper.Map'. Failures here come from decoding the backup stream or writing the intermediate map buffers.

Source

Thrown at worker/restore_map.go:855

			for ns := range dropNs {
				localDropNs[ns] = struct{}{}
			}
			in := &loadBackupInput{
				preds:     predSet,
				dropNs:    localDropNs,
				version:   manifest.Version,
				restoreTs: req.RestoreTs,
				// Only map the schema keys corresponding to the latest backup.
				keepSchema:              i == 0,
				compression:             manifest.Compression,
				fromNamespace:           req.FromNamespace,
				isNamespaceAwareRestore: req.IsNamespaceAwareRestore,
			}

			// This would stream the backups from the source, and map them in
			// Dgraph compatible format on disk.
			if err := mapper.Map(br, in); err != nil {
				return nil, errors.Wrap(err, "mapper.Map")
			}
			if err := br.Close(); err != nil {
				return nil, errors.Wrap(err, "br.Close")
			}
		}
		for _, op := range manifest.DropOperations {
			switch op.DropOp {
			case pb.DropOperation_ALL:
				dropAll = true
			case pb.DropOperation_DATA:
				if op.DropValue == "" {
					// In 2103, we do not support namespace level drop data.
					dropAll = true
					continue
				}
				ns, err := strconv.ParseUint(op.DropValue, 0, 64)
				if err != nil {
					return nil, errors.Wrap(err, "map phase failed to parse namespace")

View on GitHub (pinned to 759e242be6)

Solutions

1. Read the wrapped cause to distinguish decode vs I/O failure.
2. Check free disk space and write permissions on mapDir (the map-phase scratch directory).
3. If decode/corruption, verify backup integrity and re-take the backup if needed.
4. Retry the restore; transient storage errors during long restores are common.
5. Increase resource limits (fds, memory) if the failure correlates with very large groups.

Example fix

// before
// mapDir on a nearly full volume
mapDir := "/var/tmp/map"
// after
// ensure the scratch dir exists on a volume with space for ~backup size
os.MkdirAll(mapDir, 0700)
x.AssertTruef(x.DiskFree(mapDir) > needed, "insufficient disk for map phase")

// pre-flight disk/permission check for the map scratch dir
if err := os.MkdirAll(mapDir, 0700); err != nil { return err }
if free, _ := diskFree(mapDir); free < requiredBytes { return errors.New("insufficient disk for map phase") }

if _, err := worker.RunMapper(req, mapDir); err != nil {
    if strings.Contains(err.Error(), "mapper.Map") {
        return fmt.Errorf("map phase failed: check mapDir disk space/permissions and backup integrity: %w", err)
    }
    return err
}

When it happens

Trigger: mapper.Map(br, in) fails mid-stream: corrupted backup data, decode error on a key/value, or an I/O error writing to mapDir buffers (disk full, permissions).

Common situations: Disk exhaustion on the node running restore (mapFileSz buffers cannot be written); mapDir not writable; truncated/corrupt backup object; running out of memory/fd limits while streaming large backups.

Related errors

• another restore operation is already running
• Pending transactions found. Please retry operation
• while retrieving manifests
• cannot wait for restore ts %d
• cannot propose restore request

AI-assisted analysis of dgraph-io/dgraph@759e242be6 (2026-09-01). Data as JSON: /api/errors/927ad59c7b7b0894. Report an issue: GitHub.