grpc-ecosystem/grpc-gateway · error

failed to register option in %s: %w

Error message

failed to register option in %s: %w

What it means

registerOpenAPIOptions wraps errors from registry.RegisterOpenAPIOptions, indicating the config file parsed fine but one or more OpenAPI options could not be applied to the registry (e.g. selector does not match any service/method, or conflicting option registration). The yamlSourceLogName identifies which config file caused it.

Source

Thrown at internal/descriptor/openapi_configuration.go:44

		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
}

func registerOpenAPIOptions(registry *Registry, openAPIConfig *openapiconfig.OpenAPIConfig, yamlSourceLogName string) error {
	if openAPIConfig.OpenapiOptions == nil {
		// Nothing to do
		return nil
	}

	if err := registry.RegisterOpenAPIOptions(openAPIConfig.OpenapiOptions); err != nil {
		return fmt.Errorf("failed to register option in %s: %w", yamlSourceLogName, err)
	}
	return nil
}

// LoadOpenAPIConfigFromYAML loads an  OpenAPI Configuration from the given YAML file
// and registers the OpenAPI options the given registry.
// This must be done after loading the proto file.
func (r *Registry) LoadOpenAPIConfigFromYAML(yamlFile string) error {
	yamlFileContents, err := os.ReadFile(yamlFile)
	if err != nil {
		return fmt.Errorf("failed to read OpenAPI Configuration description from %q: %w", yamlFile, err)
	}

	config, err := loadOpenAPIConfigFromYAML(yamlFileContents, yamlFile)
	if err != nil {
		return err
	}

View on GitHub (pinned to a58a4436a3)

Solutions

1. Ensure LoadFile/LoadProto runs before LoadOpenAPIConfigFromYAML
2. Fix the selector strings to match actual fully-qualified service/method names in your protos
3. Remove stale entries for methods/services no longer defined
4. Read the wrapped (%w) inner error from RegisterOpenAPIOptions for the specific offending option

Example fix

// before (selector matches nothing)
selector: "Foo.Bar"
// after
selector: "example.hello.Greeter.SayHello"

if err := reg.LoadOpenAPIConfigFromYAML(path); err != nil {
    if strings.Contains(err.Error(), "failed to register option") {
        log.Fatalf("check selectors in %s: %v", path, err)
    }
    return err
}

When it happens

Trigger: LoadOpenAPIConfigFromYAML with an OpenAPIOptions entry whose selector points to a service/method/message not present in the loaded protos, or an option structure that fails validation during registration.

Common situations: Config referencing methods renamed or removed from the proto; selector syntax wrong (missing leading package name); loading the config before loading the proto file (LoadOpenAPIConfigFromYAML must run after loading protos).

Related errors

• selector %q in %v must specify a single service method witho
• failed to parse gRPC API Configuration from YAML in %q: %w
• failed to parse gRPC API Configuration from YAML in %q: %w
• failed to parse OpenAPI Configuration from YAML in %q: %w

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