grpc-ecosystem/grpc-gateway · error

failed to parse gRPC API Configuration from YAML in %q: %w

Error message

failed to parse gRPC API Configuration from YAML in %q: %w

What it means

loadOpenAPIConfigFromYAML fails when yaml.Unmarshal cannot parse the OpenAPI/gRPC API configuration file as valid YAML. The error is raised before any protojson decoding, and wraps the yaml library's parse error (line/column info included).

Source

Thrown at internal/descriptor/openapi_configuration.go:16

package descriptor

import (
	"encoding/json"
	"fmt"
	"os"

	"github.com/grpc-ecosystem/grpc-gateway/v2/internal/descriptor/openapiconfig"
	"go.yaml.in/yaml/v3"
	"google.golang.org/protobuf/encoding/protojson"
)

func loadOpenAPIConfigFromYAML(yamlFileContents []byte, yamlSourceLogName string) (*openapiconfig.OpenAPIConfig, error) {
	var yamlContents interface{}
	if err := yaml.Unmarshal(yamlFileContents, &yamlContents); err != nil {
		return nil, fmt.Errorf("failed to parse gRPC API Configuration from YAML in %q: %w", yamlSourceLogName, err)
	}

	jsonContents, err := json.Marshal(yamlContents)
	if err != nil {
		return nil, err
	}

	// Reject unknown fields because OpenAPIConfig is only used here
	unmarshaler := protojson.UnmarshalOptions{
		DiscardUnknown: false,
	}

	openapiConfiguration := openapiconfig.OpenAPIConfig{}
	if err := unmarshaler.Unmarshal(jsonContents, &openapiConfiguration); err != nil {
		return nil, fmt.Errorf("failed to parse OpenAPI Configuration from YAML in %q: %w", yamlSourceLogName, err)
	}

	return &openapiConfiguration, nil

View on GitHub (pinned to a58a4436a3)

Solutions

1. Run a YAML linter (yamllint) on the config file and fix the reported line/column
2. Replace tabs with spaces in the YAML file
3. Validate that the file parses standalone (e.g. `python -c "import yaml,sys; yaml.safe_load(open(sys.argv[1]))" file.yaml`)
4. Diff the config against a known-good example from the repo (internal/examples)

Example fix

// before (invalid: tab indentation)
type:
	google.api.HttpRule
// after
type: google.api.HttpRule

if err := yaml.Unmarshal(contents, &map[string]interface{}{}); err != nil {
    return fmt.Errorf("invalid YAML in config: %w", err)
}

if err := reg.LoadOpenAPIConfigFromYAML(path); err != nil {
    if strings.Contains(err.Error(), "failed to parse gRPC API Configuration from YAML") {
        log.Fatalf("fix YAML syntax in %s: %v", path, err)
    }
    return err
}

When it happens

Trigger: Calling LoadOpenAPIConfigFromYAML (public entry) with file contents containing YAML syntax errors: bad indentation, tabs for indentation, unbalanced quotes/brackets, or invalid YAML constructs.

Common situations: Hand-edited YAML config with a stray tab or missing space after a colon; heredoc-generated config with broken indentation; copy-pasted config losing indentation.

Understand the failure class

• Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

• failed to parse gRPC API Configuration from YAML in %q: %w
• unexpected number of yaml nodes
• selector %q in %v must specify a single service method witho
• failed to parse OpenAPI Configuration from YAML in %q: %w
• failed to register option in %s: %w

AI-assisted analysis of grpc-ecosystem/grpc-gateway@a58a4436a3 (2026-09-02). Data as JSON: /api/errors/630d92e59aab5666. Report an issue: GitHub.