{"record":{"id":"bfdfaae1f9030329","repo":"dgraph-io/dgraph","slug":"error-upgrading-acl-rules-w","errorCode":null,"errorMessage":"error upgrading ACL rules: %w","messagePattern":"error upgrading ACL rules: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"upgrade/change_v20.03.0.go","lineNumber":102,"sourceCode":"\t\t\t\t{\n\t\t\t\t\tSubject:   group.UID,\n\t\t\t\t\tPredicate: \"dgraph.acl.rule\",\n\t\t\t\t\tObjectId:  newRuleStr,\n\t\t\t\t},\n\t\t\t}...)\n\n\t\t\tcounter++\n\t\t}\n\t}\n\n\t// Nothing to do.\n\tif len(nquads) == 0 {\n\t\tfmt.Println(\"nothing to do: no old rules found in the cluster\")\n\t\treturn nil\n\t}\n\n\tif err := mutateWithClient(dg, &api.Mutation{Set: nquads}); err != nil {\n\t\treturn fmt.Errorf(\"error upgrading ACL rules: %w\", err)\n\t}\n\tfmt.Println(\"Successfully upgraded ACL rules.\")\n\n\tdeleteOld := Upgrade.Conf.GetBool(\"deleteOld\")\n\tif deleteOld {\n\t\terr := alterWithClient(dg, &api.Operation{\n\t\t\tDropOp:    api.Operation_ATTR,\n\t\t\tDropValue: \"dgraph.group.acl\",\n\t\t})\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"error deleting old acl predicates: %w\", err)\n\t\t}\n\t\tfmt.Println(\"Successfully deleted old rules.\")\n\t}\n\n\treturn nil\n}\n","sourceCodeStart":84,"sourceCodeEnd":120,"githubUrl":"https://github.com/dgraph-io/dgraph/blob/759e242be62c91f8d084da06ad0c8d21256d9c07/upgrade/change_v20.03.0.go#L84-L120","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Re-run the upgrade with valid admin/root credentials so the mutation is authorized","Check network connectivity and alpha health, then retry the upgrade (mutations are idempotent here via blank nodes... verify for duplicates first)","Inspect Dgraph server logs for the underlying mutation rejection reason","If ACLs aren't needed, skip ACL migration entirely instead of forcing the mutation"],"exampleFix":"// before\ndgraph upgrade --alpha alpha1:9080   // no creds on ACL cluster -> permission denied\n// after\ndgraph upgrade --alpha alpha1:9080 --creds groot:password","handlingStrategy":"retry","validationCode":"// ensure creds work before migrating\nif err := mutateWithClient(dg, &api.Mutation{Set: []*api.NQuad{probeNQuad}}); err != nil {\n    return fmt.Errorf(\"client cannot write; check --creds: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"if err := upgradeACLRules(); err != nil {\n    if strings.Contains(err.Error(), \"error upgrading ACL rules\") {\n        // verify creds/health, then re-run upgrade (check for duplicate rules first)\n    }\n    return err\n}","preventionTips":["Run the upgrade as a user with write permission on ACL predicates","Check alpha health and connection stability before the migration","Deduplicate/verify results if re-running after a partial mutation"],"tags":["upgrade","acl","mutation","dgraph"],"backgroundTag":"acl-migration-query-failure","analyzedSha":"759e242be62c91f8d084da06ad0c8d21256d9c07","analyzedAt":"2026-09-01T14:42:12.034Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}