crowdsecurity/crowdsec · error

failed to validate schema %s: %w

Error message

failed to validate schema %s: %w

What it means

After parsing, LoadSchema calls doc.Validate to confirm the document is a valid OpenAPI 3 schema (with examples validation disabled). Structural violations — missing required fields like 'info' or 'paths', invalid parameter/response objects, bad $ref targets inside the document — produce this wrapped error, so a broken spec never reaches request validation.

Source

Thrown at pkg/appsec/api_validation/api_validation.go:333

	if err := options.OnMethodNotAllowed.validate(); err != nil {
		return fmt.Errorf("on_method_not_allowed: %w", err)
	}
	if err := options.OnUnsupportedSecurityScheme.validate(); err != nil {
		return fmt.Errorf("on_unsupported_security_scheme: %w", err)
	}

	loader := openapi3.NewLoader()
	rv.loaders[ref] = loader

	doc, err := loader.LoadFromData([]byte(schema))
	if err != nil {
		return fmt.Errorf("failed to load schema %s: %w", ref, err)
	}

	// Is it a valid OpenAPI schema?
	// TODO: look into opts, should we expose some of them to the user ?
	if err := doc.Validate(loader.Context, openapi3.DisableExamplesValidation()); err != nil {
		return fmt.Errorf("failed to validate schema %s: %w", ref, err)
	}

	rv.warnUnsupportedSecuritySchemes(ref, doc, options.OnUnsupportedSecurityScheme)

	router, err := legacyrouter.NewRouter(doc)
	if err != nil {
		return fmt.Errorf("failed to create router for schema ref %s: %w", ref, err)
	}

	rv.openAPISchemas[ref] = SchemaData{
		Schema:  doc,
		Router:  router,
		Options: options,
	}

	rv.logger.Infof("loaded schema for ref %s", ref)
	return nil
}

View on GitHub (pinned to 909b515798)

Solutions

1. Fix each violation listed in the wrapped validation error message (they name the JSON path).
2. Convert Swagger 2.0 specs to OpenAPI 3 (e.g. with swagger2openapi) before loading.
3. Run a local validator (kin-openapi/openapi3filter, spectral) against the file to see all errors up front.
4. Restore missing required sections: openapi: 3.x.x, info:, paths:.

Example fix

// before
info:            # missing version
  title: my api

// after
openapi: 3.0.3
info:
  title: my api
  version: 1.0.0

// full spec validation before registering
loader := openapi3.NewLoader()
doc, err := loader.LoadFromData([]byte(schema))
if err == nil {
    if verr := doc.Validate(loader.Context, openapi3.DisableExamplesValidation()); verr != nil {
        return fmt.Errorf("spec %q invalid: %w", ref, verr)
    }
}

if err := rv.LoadSchema(ref, schema, opts); err != nil {
    if strings.Contains(err.Error(), "failed to validate schema") {
        log.Errorf("openapi validation failed for %s: %v", ref, err)
    }
    return err
}

When it happens

Trigger: Loading an OpenAPI document that parses but violates the OpenAPI 3 spec: missing openapi/info/paths, operation without responses, a $ref to a non-existent local component, wrong types on schema attributes.

Common situations: Specs exported from tools targeting OpenAPI 2 (Swagger) instead of 3; hand-written specs missing required top-level fields; edited specs with dangling $ref pointers; version drift between spec generator and OpenAPI 3 validation rules.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• invalid schema name
• authorization header not found
• auth token is required but not provided
• ref cannot be empty
• unknown body decoder %q

AI-assisted analysis of crowdsecurity/crowdsec@909b515798 (2026-09-06). Data as JSON: /api/errors/6323a7690a5134fc. Report an issue: GitHub.