{"record":{"id":"95058d0fce840b6e","repo":"hasura/graphql-engine","slug":"unable-to-fetch-introspection-schema-w","errorCode":null,"errorMessage":"unable to fetch introspection schema: %w","messagePattern":"unable to fetch introspection schema: %w","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cli/commands/actions_codegen.go","lineNumber":103,"sourceCode":"\ntype actionsCodegenOptions struct {\n\tEC         *cli.ExecutionContext\n\tactions    []string\n\tderiveFrom string\n}\n\nfunc (o *actionsCodegenOptions) run() (err error) {\n\tvar (\n\t\top            errors.Op = \"commands.actionsCodegenOptions.run\"\n\t\tderivePayload types.DerivePayload\n\t)\n\tif o.deriveFrom != \"\" {\n\t\tderivePayload.Operation = strings.TrimSpace(o.deriveFrom)\n\t\to.EC.Spin(\"Deriving a Hasura operation...\")\n\n\t\tintroSchema, err := o.EC.APIClient.V1Graphql.GetIntrospectionSchema()\n\t\tif err != nil {\n\t\t\treturn errors.E(op, fmt.Errorf(\"unable to fetch introspection schema: %w\", err))\n\t\t}\n\n\t\tderivePayload.IntrospectionSchema = introSchema\n\n\t\to.EC.Spinner.Stop()\n\t}\n\n\tif o.EC.Config.ActionConfig.Codegen.Framework == \"\" {\n\t\treturn errors.E(\n\t\t\top,\n\t\t\tstderrors.New(`could not find codegen config. For adding codegen config, run:\n\n  hasura actions use-codegen`),\n\t\t)\n\t}\n\n\t// if no actions are passed, perform codegen for all actions\n\to.EC.Spin(\"Generating code...\")","sourceCodeStart":85,"sourceCodeEnd":121,"githubUrl":"https://github.com/hasura/graphql-engine/blob/724551b9ae87845594ef0408cff0e50eb6c90dc5/cli/commands/actions_codegen.go#L85-L121","documentation":"Thrown when `hasura actions codegen --derive-from` needs the GraphQL introspection schema to derive an action, and the call to the Hasura GraphQL engine's introspection endpoint (o.EC.APIClient.V1Graphql.GetIntrospectionSchema()) fails. This means the CLI could not reach or query the configured Hasura server.","triggerScenarios":"Running actions codegen with --derive-from while the Hasura engine at --endpoint is down, unreachable, protected by an invalid --admin-secret, or returning a non-200/error response from /v1/graphql introspection.","commonSituations":"Wrong or missing --endpoint/--admin-secret flags, expired admin secret, server behind auth proxy rejecting the CLI, local docker engine not started, or Hasura version that errors on the introspection query the CLI sends.","solutions":["Verify the engine is up: curl the /healthz endpoint of your --endpoint.","Re-run with the correct --endpoint and --admin-secret (or HASURA_GRAPHQL_ADMIN_SECRET env var).","Check CLI-to-server network reachability (DNS, VPN, proxy, TLS).","If introspection is disabled/restricted on the server, enable it or derive the action manually without --derive-from.","Check for version mismatch between CLI and server; align versions."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"curl -sf \"$ENDPOINT/healthz\" && curl -sf -H \"X-Hasura-Admin-Secret: $SECRET\" \"$ENDPOINT/v1/graphql\" -d '{\"query\":\"{ __typename }\"}'","typeGuard":null,"tryCatchPattern":"Catch the error, inspect the wrapped cause for HTTP status (401 => fix admin secret, connection refused => fix endpoint) and surface a targeted message.","preventionTips":["Always pass --endpoint and --admin-secret explicitly in scripts.","Health-check the server before running derive commands.","Keep CLI and server versions aligned."],"tags":["graphql","introspection","hasura-cli","network","auth"],"backgroundTag":"graphql-introspection-failed","analyzedSha":"724551b9ae87845594ef0408cff0e50eb6c90dc5","analyzedAt":"2026-08-28T07:32:55.105Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}