{"record":{"id":"dd373ecbab838f3a","repo":"hasura/graphql-engine","slug":"error-building-project-metadata-w","errorCode":null,"errorMessage":"error building project metadata: %w","messagePattern":"error building project metadata: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/commands/metadata_handlers.go","lineNumber":100,"sourceCode":"\t\t}\n\n\t\tif len(o.rawOutput) != 0 {\n\t\t\t// if not a dry run fetch metadata from and server and print it to stdout\n\t\t\terr := getMetadataFromServerAndWriteToStdoutByFormat(o.EC, rawOutputFormat(o.rawOutput))\n\t\t\tif err != nil {\n\t\t\t\treturn errors.E(op, err)\n\t\t\t}\n\n\t\t\treturn nil\n\t\t}\n\n\t\treturn nil\n\t}\n\n\tif o.DryRun {\n\t\tprojectMetadataJSON, err := metadataHandler.BuildJSONMetadata()\n\t\tif err != nil {\n\t\t\treturn errors.E(op, fmt.Errorf(\"error building project metadata: %w\", err))\n\t\t}\n\n\t\tif o.DryRun && len(o.rawOutput) == 0 {\n\t\t\t// ie users who probably expect old behaviour\n\t\t\t// show a warning about change in behaviour\n\t\t\to.rawOutput = string(rawOutputFormatJSON)\n\t\t\to.EC.Logger.Warn(\n\t\t\t\t\"behaviour of --dry-run flag has changed from v2.0.0. It used to show a diff between metadata on server and local project\",\n\t\t\t)\n\t\t\to.EC.Logger.Warn(\n\t\t\t\t\"new behaviour is to output local project metadata as JSON by default. The output format is configurable by -o flag eg: `hasura metadata apply --dry-run -o yaml`\",\n\t\t\t)\n\t\t\to.EC.Logger.Warn(\n\t\t\t\t\"the old behaviour can be achieved using `hasura metadata diff` command\",\n\t\t\t)\n\t\t}\n\n\t\tif err := writeByOutputFormat(","sourceCodeStart":82,"sourceCodeEnd":118,"githubUrl":"https://github.com/hasura/graphql-engine/blob/724551b9ae87845594ef0408cff0e50eb6c90dc5/cli/commands/metadata_handlers.go#L82-L118","documentation":"This error occurs when the CLI's dry-run mode for `metadata apply` fails to build a JSON representation of the project's metadata. The BuildJSONMetadata call aggregates resource states (tables, relationships, functions, etc.) into a JSON document that would be applied, and any failure in that aggregation (server query failure, malformed resource state) surfaces here. It wraps the underlying error with %w so the root cause is visible in the chain.","triggerScenarios":"Running `metadata apply --dry-run` (o.DryRun == true) when metadataHandler.BuildJSONMetadata() returns an error — typically because a query to the server's metadata API failed, a tracked resource could not be resolved, or the assembled metadata graph failed validation.","commonSituations":"Running a dry-run apply against an unreachable or misconfigured server endpoint; using an admin secret that lacks metadata permissions; a server version that returns unexpected resource shapes; a corrupted/incomplete metadata state on the server.","solutions":["Verify server connectivity and credentials (endpoint URL, admin secret) and retry the dry-run","Inspect the wrapped error (err chain) to identify which resource or query failed during metadata aggregation","Check that the CLI version is compatible with the server version's metadata API","If the server metadata itself is broken, run `metadata inconsistency list` to diagnose and fix inconsistencies before dry-running"],"exampleFix":"# before\nhasura metadata apply --dry-run  # fails: error building project metadata\n# after\n# verify connectivity first\nhasura metadata export  # confirms API access works\nhasura metadata apply --dry-run","handlingStrategy":"validation","validationCode":"// before dry-run, verify basic API access\nif _, err := ec.APIClient.V1Metadata.ExportMetadata(); err != nil {\n  return fmt.Errorf(\"server not ready for metadata operations: %w\", err)\n}\n// then run dry-run apply","typeGuard":null,"tryCatchPattern":"if err := opts.Apply(); err != nil {\n  if strings.Contains(err.Error(), \"error building project metadata\") {\n    // surface wrapped cause, check connectivity/permissions\n  }\n  return err\n}","preventionTips":["Validate server connectivity and admin secret before dry-run operations","Keep CLI and server versions aligned","Run `metadata inconsistency list` before apply workflows to catch corrupt server state"],"tags":["metadata","dry-run","cli","go"],"backgroundTag":"metadata-build-failed","analyzedSha":"724551b9ae87845594ef0408cff0e50eb6c90dc5","analyzedAt":"2026-08-28T07:32:55.105Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}