{"record":{"id":"dd86c39ae778e3bf","repo":"hasura/graphql-engine","slug":"determining-server-metadata-inconsistency-w","errorCode":null,"errorMessage":"determining server metadata inconsistency: %w","messagePattern":"determining server metadata inconsistency: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/internal/scripts/update-project-v3.go","lineNumber":66,"sourceCode":"\n\t// pre checks\n\tif opts.EC.Config.Version != cli.V2 && !opts.MoveStateOnly {\n\t\treturn errors.E(op, \"project should be using config V2 to be able to update to V3\")\n\t}\n\n\tif !opts.EC.HasMetadataV3 {\n\t\treturn errors.E(\n\t\t\top,\n\t\t\tfmt.Errorf(\n\t\t\t\t\"cannot upgrade: unsupported server version %v, config V3 is supported only on server with metadata version >= 3\",\n\t\t\t\topts.EC.Version.Server,\n\t\t\t),\n\t\t)\n\t}\n\n\tr, err := opts.EC.APIClient.V1Metadata.GetInconsistentMetadata()\n\tif err != nil {\n\t\treturn errors.E(op, fmt.Errorf(\"determining server metadata inconsistency: %w\", err))\n\t}\n\n\tif !r.IsConsistent {\n\t\treturn errors.E(op, \"cannot continue: metadata is inconsistent on the server\")\n\t}\n\n\topts.Logger.Infof(\n\t\t\"The upgrade process will make some changes to your project directory, It is advised to create a backup project directory before continuing\",\n\t)\n\topts.Logger.Warn(`Config V3 is expected to be used with servers >=v2.0.0-alpha.1`)\n\topts.Logger.Warn(\n\t\t`During the update process CLI uses the server as the source of truth, so make sure your server is upto date`,\n\t)\n\topts.Logger.Warn(`The update process replaces project metadata with metadata on the server`)\n\topts.Logger.Infof(\n\t\t\"Using %s server at %s for update\",\n\t\topts.EC.Version.GetServerVersion(),\n\t\topts.EC.Config.Endpoint,","sourceCodeStart":48,"sourceCodeEnd":84,"githubUrl":"https://github.com/hasura/graphql-engine/blob/724551b9ae87845594ef0408cff0e50eb6c90dc5/cli/internal/scripts/update-project-v3.go#L48-L84","documentation":"Thrown by scripts.UpdateProjectV3 when the API call V1Metadata.GetInconsistentMetadata fails, i.e. the CLI could not even ask the server whether its metadata is consistent. The %w wraps the HTTP/GraphQL transport or server error. This is a network/server availability problem, not a metadata-consistency verdict (a separate error covers actual inconsistency).","triggerScenarios":"Running update-project-v3 when the Hasura endpoint is unreachable, returns 5xx, has invalid admin secret/auth, TLS certificate issues, or the server is restarting.","commonSituations":"Wrong HASURA_GRAPHQL_ENDPOINT, missing/wrong HASURA_GRAPHQL_ADMIN_SECRET, expired auth token, self-signed TLS cert, server pod down during a k8s rollout, local Docker not started.","solutions":["Verify the server is up: curl $HASURA_GRAPHQL_ENDPOINT/healthz","Check admin secret / auth env vars are correct for the target environment","Fix TLS issues (trust the CA, or use a proper certificate) and retry the upgrade command"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// preflight before update-project-v3:\nif _, err := ec.APIClient.V1Metadata.GetInconsistentMetadata(); err != nil {\n\treturn fmt.Errorf(\"server unreachable or auth failed: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"for attempt := 0; attempt < 3; attempt++ {\n\terr := scripts.UpdateProjectV3(opts)\n\tif err == nil || !strings.Contains(err.Error(), \"determining server metadata inconsistency\") {\n\t\tbreak\n\t}\n\ttime.Sleep(2 * time.Second << attempt) // retry transient transport failures\n}","preventionTips":["Verify endpoint health and admin secret before running upgrade scripts","Retry transient network failures with backoff","Run upgrades against stable, fully-started servers"],"tags":["go","network","metadata-consistency","upgrade","hasura-cli"],"backgroundTag":"metadata-api-request-failed","analyzedSha":"724551b9ae87845594ef0408cff0e50eb6c90dc5","analyzedAt":"2026-08-28T07:32:55.105Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}