dgraph-io/dgraph · error

Unexpected meta %d for key %s

Error message

Unexpected meta %d for key %s

What it means

During the restore map phase, each key-value item read from a backup is dispatched based on its UserMeta byte. This error is thrown in the default case of that switch when the meta byte holds a value the current Dgraph version's restore code does not recognize, meaning the backup stream contains an item type this code path cannot interpret.

Source

Thrown at worker/restore_map.go:566

					return err
				}

				if strings.HasSuffix(update.Predicate, "dgraph.xid") && !update.Unique && schema.IsUniqueDgraphXid {
					update.Unique = true
				}

				kv.Value, err = proto.Marshal(&update)
				if err != nil {
					return err
				}
			}

			if err := toBuffer(kv, version); err != nil {
				return err
			}

		default:
			return errors.Errorf(
				"Unexpected meta %d for key %s", kv.UserMeta[0], hex.Dump(kv.Key))
		}
		return nil
	}

	mergeBuffer := func() error {
		if buf.IsEmpty() {
			return nil
		}
		atomic.AddUint64(&m.bytesProcessed, uint64(buf.LenNoPadding()))

		m.bufLock.Lock()
		defer m.bufLock.Unlock()

		x.Check2(m.buf.Write(buf.Bytes()))
		buf.Reset()

		if m.buf.LenNoPadding() < mapFileSz {

View on GitHub (pinned to 759e242be6)

Solutions

1. Check that the Dgraph version performing the restore is >= the version that created the backup (restore is not backward compatible with unknown meta values).
2. Verify backup integrity by re-uploading or re-downloading the backup objects and comparing checksums.
3. Re-create the backup with a matching Dgraph version and retry the restore.
4. If you control the code, extend the switch in worker/restore_map.go to handle (or explicitly ignore) the new meta value instead of erroring.

Example fix

// before
default:
    return errors.Errorf("Unexpected meta %d for key %s", kv.UserMeta[0], hex.Dump(kv.Key))
// after
case x.MetaNewKind: // handle the meta emitted by the newer backup format
    if err := toBufferNewKind(kv, version); err != nil {
        return err
    }
default:
    return errors.Errorf("Unexpected meta %d for key %s", kv.UserMeta[0], hex.Dump(kv.Key))

// before restore, scan backup kvs for known meta values
// (conceptual): ensure kv.UserMeta[0] is one of the meta constants
// your Dgraph version supports; otherwise the restore will abort.
func metaKnown(b byte, known map[byte]bool) bool { return known[b] }

When it happens

Trigger: kv.UserMeta[0] contains a value other than the known meta constants (e.g. 0 for data, 1 for index/schema meta) while processing a backup via toBuffer in the mapper's item handler.

Common situations: Restoring a backup produced by a newer or patched Dgraph version whose writer emits extra meta types; a corrupted or truncated backup file where bytes are misaligned; manually edited or third-party-generated backup objects.

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/5f43fc495a314d42. Report an issue: GitHub.