dgraph-io/dgraph · error

error upgrading ACL rules: %w

Error message

error upgrading ACL rules: %w

What it means

After converting old ACL rules into new-style NQuads, upgradeACLRules writes them with mutateWithClient. If the mutation is rejected (network, auth, schema/ACL constraints), the upgrade fails wrapped with this message, leaving old rules intact but migration incomplete.

Source

Thrown at upgrade/change_v20.03.0.go:102

				{
					Subject:   group.UID,
					Predicate: "dgraph.acl.rule",
					ObjectId:  newRuleStr,
				},
			}...)

			counter++
		}
	}

	// Nothing to do.
	if len(nquads) == 0 {
		fmt.Println("nothing to do: no old rules found in the cluster")
		return nil
	}

	if err := mutateWithClient(dg, &api.Mutation{Set: nquads}); err != nil {
		return fmt.Errorf("error upgrading ACL rules: %w", err)
	}
	fmt.Println("Successfully upgraded ACL rules.")

	deleteOld := Upgrade.Conf.GetBool("deleteOld")
	if deleteOld {
		err := alterWithClient(dg, &api.Operation{
			DropOp:    api.Operation_ATTR,
			DropValue: "dgraph.group.acl",
		})
		if err != nil {
			return fmt.Errorf("error deleting old acl predicates: %w", err)
		}
		fmt.Println("Successfully deleted old rules.")
	}

	return nil
}

View on GitHub (pinned to 759e242be6)

Solutions

1. Re-run the upgrade with valid admin/root credentials so the mutation is authorized
2. Check network connectivity and alpha health, then retry the upgrade (mutations are idempotent here via blank nodes... verify for duplicates first)
3. Inspect Dgraph server logs for the underlying mutation rejection reason
4. If ACLs aren't needed, skip ACL migration entirely instead of forcing the mutation

Example fix

// before
dgraph upgrade --alpha alpha1:9080   // no creds on ACL cluster -> permission denied
// after
dgraph upgrade --alpha alpha1:9080 --creds groot:password

// ensure creds work before migrating
if err := mutateWithClient(dg, &api.Mutation{Set: []*api.NQuad{probeNQuad}}); err != nil {
    return fmt.Errorf("client cannot write; check --creds: %w", err)
}

if err := upgradeACLRules(); err != nil {
    if strings.Contains(err.Error(), "error upgrading ACL rules") {
        // verify creds/health, then re-run upgrade (check for duplicate rules first)
    }
    return err
}

When it happens

Trigger: Running mutateWithClient(dg, &api.Mutation{Set: nquads}) during the 20.03 upgrade when the Dgraph client lacks permission to write dgraph.group.acl / rule predicates, the connection drops, or a transaction conflict occurs.

Common situations: Running the upgrade tool without super-admin credentials on an ACL-enabled cluster; alpha going away mid-upgrade; read-only or health-degraded cluster; TLS configuration mismatch.

Related errors

• error querying old ACL rules: %w
• unable to parse ACLs: %v
• unable to unmarshal ACL: %v :: %w
• error deleting old acl predicates: %w
• error deleting old predicate %s

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