hasura/graphql-engine · error

error while parsing the endpoint :%w

Error message

error while parsing the endpoint :%w

What it means

A type referenced in the metadata (e.g. as a field type or argument type) by its qualified name has not been defined anywhere. The resolver must be able to look up every referenced custom type name.

Source

Thrown at cli/cli.go:803

		}
		// set name of metadata directory
		ec.MetadataDir = filepath.Join(ec.ExecutionDirectory, ec.Config.MetadataDirectory)

		_, err := os.Stat(ec.MetadataDir)
		if err != nil && stderrors.Is(err, fs.ErrNotExist) && len(ec.MetadataFile) == 0 {
			err = os.MkdirAll(ec.MetadataDir, os.ModePerm)
			if err != nil {
				return errors.E(op, fmt.Errorf("cannot create metadata directory: %w", err))
			}
		}
	}

	ec.Logger.Debug("graphql engine endpoint: ", ec.Config.Endpoint)
	ec.Logger.Debug(strings.Repeat("*", len(ec.Config.AdminSecret)))

	uri, err := url.Parse(ec.Config.Endpoint)
	if err != nil {
		return errors.E(op, fmt.Errorf("error while parsing the endpoint :%w", err))
	}

	// check if server is using metadata v3
	if ec.Config.APIPaths.V1Query != "" {
		uri.Path = path.Join(uri.Path, ec.Config.APIPaths.V1Query)
	} else {
		uri.Path = path.Join(uri.Path, "v1/query")
	}

	requestUri := uri.String()

	metadata, err := commonmetadata.New(httpClient, requestUri).ExportMetadata()
	if err != nil {
		return errors.E(op, err)
	}

	var v struct {
		Version int `json:"version"`

View on GitHub (pinned to 724551b9ae)

Solutions

1. Define the missing type with the exact qualified name
2. Fix the reference (namespace + name) to point at an existing type
3. Ensure the subgraph/type definition containing it is included in the build

Example fix

// before
models:
  users:
    fields:
      address: Address   // Address not defined
// after
types:
  Address: { fields: { ... } }
models:
  users:
    fields:
      address: Address

let defined: HashSet<_> = all_declared_type_names(&metadata).collect();
for t in referenced_type_names(&metadata) {
    assert!(defined.contains(&t), "type {t} referenced but not defined");
}

When it happens

Trigger: Using a type like `my_type` in a model field or command argument when no object type, scalar type, or enum with that qualified name is declared in the metadata.

Common situations: Forgetting to include the type definition file; renaming a type without updating references; referencing types defined in another subgraph not being resolved; circular or ordering issues in metadata files.

Related errors

• failed to get version from server: %w
• cannot read config from file/env: %w
• unable to parse server endpoint: %w
• setting up codegen-assets repo failed (this is required for
• error building metadata

AI-assisted analysis of hasura/graphql-engine@724551b9ae (2026-08-28). Data as JSON: /api/errors/8378913065695448. Report an issue: GitHub.