dgraph-io/dgraph · error

while upgrading persisted query

Error message

while upgrading persisted query

What it means

OfflineUpgradeFrom2011To2103 wraps any fixPersistedQuery failure with this message. It means the persisted-query schema/type rewrite portion of the 20.11 -> 21.03 offline upgrade failed; the wrapped error chain contains the specific badger/transform cause.

Source

Thrown at upgrade/change_v21.03.0.go:441

	data, err = proto.Marshal(&tu)
	if err != nil {
		return err
	}
	entry = &badger.Entry{}
	entry.Key = x.TypeKey(x.AttrInRootNamespace("dgraph.graphql.persisted_query"))
	entry.Value = data
	entry.UserMeta = posting.BitSchemaPosting
	if err := update(entry); err != nil {
		return errors.Wrap(err, "while updating persisted query's type")
	}
	return nil
}

// OfflineUpgradeFrom2011To2103 upgrades a p directory restored from backup of 20.11 to the changes
// in 21.03. It fixes the cors, schema and drops the deprecated types/predicates.
func OfflineUpgradeFrom2011To2103(db *badger.DB) error {
	if err := fixPersistedQuery(db); err != nil {
		return errors.Wrapf(err, "while upgrading persisted query")
	}
	return errors.Wrapf(fixCors(db), "while upgrading cors")
}

View on GitHub (pinned to 759e242be6)

Solutions

1. Print the full error chain (%+v) to find the wrapped cause from fixPersistedQuery and fix it.
2. Re-restore the backup and retry the upgrade from a clean state.
3. Ensure the p directory is not in use by a running dgraph instance during the offline upgrade.
4. Check disk space and filesystem health on the node before rerunning.

Example fix

// before
if err := upgrade.OfflineUpgradeFrom2011To2103(db); err != nil { log.Fatal(err) } // prints only top message
// after
if err := upgrade.OfflineUpgradeFrom2011To2103(db); err != nil { log.Fatalf("%+v", err) } // full chain

// Validate from-version is 20.11.x before calling this upgrade path
if !strings.HasPrefix(version, "v20.11.") {
	log.Fatalf("OfflineUpgradeFrom2011To2103 expects a v20.11.x source, got %s", version)
}

func isPersistedQueryUpgradeErr(err error) bool {
	return err != nil && strings.Contains(err.Error(), "while upgrading persisted query")
}

if err := upgrade.OfflineUpgradeFrom2011To2103(db); err != nil {
	log.Fatalf("persisted query upgrade failed: %+v", err)
}

When it happens

Trigger: Calling OfflineUpgradeFrom2011To2103 (via dgraph upgrade offline) where fixPersistedQuery returns any error: failure building the schema update, marshaling, or writing schema/type badger entries.

Common situations: Version migration from Dgraph 20.11 backups to 21.03; corrupted restore output; badger write errors during migration.

Related errors

• while updating persisted query's type
• Error while updating GraphQL schema.
• Error while dropping depreciated preds/types.
• while updating persisted query's schema
• while upgrading cors

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