grpc-ecosystem/grpc-gateway · error

failed to read OpenAPI Configuration description from %q: %w

Error message

failed to read OpenAPI Configuration description from %q: %w

What it means

Registry.LoadOpenAPIConfigFromYAML wraps os.ReadFile failures when opening the OpenAPI configuration YAML file. It is identical in nature to the gRPC API Configuration read error, but for the OpenAPI config file; the OS error is preserved via %w.

Source

Thrown at internal/descriptor/openapi_configuration.go:55

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
	}

	return registerOpenAPIOptions(r, config, yamlFile)
}

View on GitHub (pinned to a58a4436a3)

Solutions

1. Check the exact path exists (ls <path>) and correct it
2. Use an absolute path or run protoc from the correct directory
3. Fix filesystem permissions
4. Ensure the file is created/copied before the protoc invocation in the build pipeline

Example fix

// before
--openapiv2_opt=openapi_configuration=openapi_conf,yaml
// after
--openapiv2_opt=openapi_configuration=openapi_conf.yaml

const path = "openapi_conf.yaml"
if _, err := os.Stat(path); err != nil {
    return fmt.Errorf("OpenAPI config %q missing before load: %w", path, err)
}

if err := reg.LoadOpenAPIConfigFromYAML(path); err != nil {
    var pe *fs.PathError
    if errors.As(err, &pe) {
        log.Fatalf("cannot read OpenAPI config %q: %v", pe.Path, pe.Err)
    }
    return err
}

When it happens

Trigger: Calling LoadOpenAPIConfigFromYAML(yamlFile) (e.g. via the openapi_configuration option of protoc-gen-openapiv2) when the file path is wrong, missing, a directory, or unreadable.

Common situations: Misspelled file name on the protoc command line; config not present in the build sandbox; running protoc from a different working directory in CI vs locally.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

• failed to read gRPC API Configuration description from %q: %
• read %s: %w

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