{"record":{"id":"a770413c07133d83","repo":"dgraph-io/dgraph","slug":"error-querying-old-acl-rules-w","errorCode":null,"errorMessage":"error querying old ACL rules: %w","messagePattern":"error querying old ACL rules: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"upgrade/change_v20.03.0.go","lineNumber":45,"sourceCode":"type group struct {\n\tUID string `json:\"uid\"`\n\tACL string `json:\"dgraph.group.acl,omitempty\"`\n}\n\ntype rule struct {\n\tPredicate  string `json:\"predicate,omitempty\"`\n\tPermission int    `json:\"perm,omitempty\"`\n}\n\ntype rules []rule\n\nfunc upgradeACLRules() error {\n\tdg, cb := x.GetDgraphClient(Upgrade.Conf, true)\n\tdefer cb()\n\n\tdata := make(map[string][]group)\n\tif err := getQueryResult(dg, queryACLGroupsBefore_v20_03_0, &data); err != nil {\n\t\treturn fmt.Errorf(\"error querying old ACL rules: %w\", err)\n\t}\n\n\tgroups, ok := data[\"rules\"]\n\tif !ok {\n\t\treturn fmt.Errorf(\"unable to parse ACLs: %v\", data)\n\t}\n\n\tcounter := 1\n\tvar nquads []*api.NQuad\n\tfor _, group := range groups {\n\t\tif group.ACL == \"\" {\n\t\t\tcontinue\n\t\t}\n\n\t\tvar rs rules\n\t\tif err := json.Unmarshal([]byte(group.ACL), &rs); err != nil {\n\t\t\treturn fmt.Errorf(\"unable to unmarshal ACL: %v :: %w\", group.ACL, err)\n\t\t}","sourceCodeStart":27,"sourceCodeEnd":63,"githubUrl":"https://github.com/dgraph-io/dgraph/blob/759e242be62c91f8d084da06ad0c8d21256d9c07/upgrade/change_v20.03.0.go#L27-L63","documentation":"During the v20.03.0 ACL upgrade, upgradeACLRules runs a query against the cluster to fetch the old dgraph.group.acl rules via getQueryResult. If that Dgraph query fails (network, auth, malformed response), the underlying error is wrapped with this message so the operator knows the ACL migration could not read the old state.","triggerScenarios":"Running the dgraph upgrade tool against a cluster where the query queryACLGroupsBefore_v20_03_0 fails: Dgraph unreachable, wrong --alpha address, missing/invalid access JWT, or the group predicates already dropped.","commonSituations":"Upgrading a cluster where ACL data was already migrated or deleted; pointing the upgrade tool at the wrong port/host; running without admin credentials; TLS mismatch between tool and server.","solutions":["Verify the Dgraph alpha HTTP/gRPC addresses passed to the upgrade tool are correct and reachable","Ensure you authenticate with valid admin credentials (access JWT) before running the upgrade","Check Dgraph server logs for the underlying query error (permission denied, connection refused, etc.)","Confirm the old ACL predicates (dgraph.group.acl) still exist — if already migrated, skip this step"],"exampleFix":"// before\ndgraph upgrade --alpha localhost:9080   // wrong port, query fails\n// after\ndgraph upgrade --alpha localhost:9082 --creds user:password   // correct address + creds","handlingStrategy":"retry","validationCode":"resp, err := http.Get(\"http://alpha:8080/health\")\nif err != nil || resp.StatusCode != http.StatusOK {\n    return errors.New(\"dgraph alpha not reachable; aborting ACL upgrade\")\n}","typeGuard":null,"tryCatchPattern":"if err := upgradeACLRules(); err != nil {\n    if strings.Contains(err.Error(), \"error querying old ACL rules\") {\n        // check connectivity/auth, back off, retry upgrade\n        return fmt.Errorf(\"ACL upgrade aborted: %w\", err)\n    }\n    return err\n}","preventionTips":["Verify alpha addresses and ports before running the upgrade tool","Authenticate with admin creds (--creds) on ACL-enabled clusters","Check /health of all alphas before starting migration","Keep a pre-upgrade backup so failed queries can be retried safely"],"tags":["upgrade","acl","dgraph","query"],"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"}