{"record":{"id":"d0c20b4acc74e940","repo":"hasura/graphql-engine","slug":"cannot-upgrade-unsupported-server-version-v-con","errorCode":null,"errorMessage":"cannot upgrade: unsupported server version %v, config V3 is supported only on server with metadata version >= 3","messagePattern":"cannot upgrade: unsupported server version (.+?), config V3 is supported only on server with metadata version >= 3","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/internal/scripts/update-project-v3.go","lineNumber":57,"sourceCode":"\t/* New flow\n\t\tConfig V2 -> Config V3\n\t\t- Warn user about creating a backup\n\t\t- Ask user for the name of database to migrate to\n\t  \t- copy state from hdb_tables to catalog state\n\t\t- Move current migration directories to a new source directory\n\t\t- Move seeds belonging to the source to a new directory\n\t\t- Update config file and version\n\t*/\n\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)","sourceCodeStart":39,"sourceCodeEnd":75,"githubUrl":"https://github.com/hasura/graphql-engine/blob/724551b9ae87845594ef0408cff0e50eb6c90dc5/cli/internal/scripts/update-project-v3.go#L39-L75","documentation":"Thrown by scripts.UpdateProjectV3 when the connected Hasura server does not advertise metadata API version 3 (opts.EC.HasMetadataV3 is false). Config V3 projects require a server with metadata version >= 3, so the upgrade is refused before touching any files.","triggerScenarios":"Running the V2->V3 project upgrade (hasura scripts update-project-v3) against a Hasura server older than v2.13-ish / one whose version_info.metadata_object_format does not report 3.","commonSituations":"Pointing the CLI at an older self-hosted Hasura (e.g. v2.9-2.12) or a stale CE deployment while trying to use the newer config V3 layout; env var HASURA_GRAPHQL_ENDPOINT pointing at the wrong environment.","solutions":["Upgrade the Hasura server to a version with metadata V3 support (>= 2.13.0, ideally latest v2.x) and retry","Verify the CLI is pointed at the intended server: check the endpoint in config.yaml / HASURA_GRAPHQL_ENDPOINT env","If the server cannot be upgraded, keep the project on config V2"],"exampleFix":"// config.yaml\n# before (targeting old server, v2 config):\nversion: 2\nendpoint: https://old-hasura.example.com\n\n# after: upgrade server >= 2.13, then re-run\n# hasura scripts update-project-v3\nversion: 3\nendpoint: https://hasura-v213.example.com","handlingStrategy":"validation","validationCode":"// before invoking UpdateProjectV3:\nif !ec.HasMetadataV3 {\n\treturn fmt.Errorf(\"server %s lacks metadata V3; upgrade server first\", ec.Version.Server)\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Check server version_info.metadata_object_format >= 3 before starting the V3 upgrade","Pin CLI and server versions together in your deployment tooling"],"tags":["go","version-mismatch","metadata-v3","upgrade","hasura-cli"],"backgroundTag":"server-version-unsupported","analyzedSha":"724551b9ae87845594ef0408cff0e50eb6c90dc5","analyzedAt":"2026-08-28T07:32:55.105Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}