{"record":{"id":"3127c15140f0827d","repo":"crowdsecurity/crowdsec","slug":"failed-to-load-schema-s-w","errorCode":null,"errorMessage":"failed to load schema %s: %w","messagePattern":"failed to load schema (.+?): %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/appsec/api_validation/api_validation.go","lineNumber":327,"sourceCode":"\t}\n\n\toptions := opts.withDefaults()\n\tif err := options.OnRouteNotFound.validate(); err != nil {\n\t\treturn fmt.Errorf(\"on_route_not_found: %w\", err)\n\t}\n\tif err := options.OnMethodNotAllowed.validate(); err != nil {\n\t\treturn fmt.Errorf(\"on_method_not_allowed: %w\", err)\n\t}\n\tif err := options.OnUnsupportedSecurityScheme.validate(); err != nil {\n\t\treturn fmt.Errorf(\"on_unsupported_security_scheme: %w\", err)\n\t}\n\n\tloader := openapi3.NewLoader()\n\trv.loaders[ref] = loader\n\n\tdoc, err := loader.LoadFromData([]byte(schema))\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to load schema %s: %w\", ref, err)\n\t}\n\n\t// Is it a valid OpenAPI schema?\n\t// TODO: look into opts, should we expose some of them to the user ?\n\tif err := doc.Validate(loader.Context, openapi3.DisableExamplesValidation()); err != nil {\n\t\treturn fmt.Errorf(\"failed to validate schema %s: %w\", ref, err)\n\t}\n\n\trv.warnUnsupportedSecuritySchemes(ref, doc, options.OnUnsupportedSecurityScheme)\n\n\trouter, err := legacyrouter.NewRouter(doc)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"failed to create router for schema ref %s: %w\", ref, err)\n\t}\n\n\trv.openAPISchemas[ref] = SchemaData{\n\t\tSchema:  doc,\n\t\tRouter:  router,","sourceCodeStart":309,"sourceCodeEnd":345,"githubUrl":"https://github.com/crowdsecurity/crowdsec/blob/909b5157986a2b2c2163300fdaef5ed01289f7d2/pkg/appsec/api_validation/api_validation.go#L309-L345","documentation":"LoadSchema parses the raw OpenAPI document bytes with kin-openapi's loader (LoadFromData). If the document is not parseable — invalid YAML/JSON, unreadable structure, or unresolvable $ref pointers to external files — the underlying loader error is wrapped as \"failed to load schema <ref>: ...\".","triggerScenarios":"Passing malformed YAML/JSON to LoadSchema; a spec containing external $ref (\"./other.yaml\") that the loader cannot resolve from disk; a file read producing truncated or empty content handed to LoadSchema.","commonSituations":"Syntax errors after hand-editing the OpenAPI file; specs split across multiple files with relative refs whose paths don't resolve in the crowdsec working directory; wrong file path in appsec config; schema file saved with BOM or mixed tabs.","solutions":["Fix the YAML/JSON syntax error reported in the wrapped message.","Inline external $ref references, or make the referenced files resolvable relative to the crowdsec process working directory.","Validate the document with a standalone OpenAPI linter (e.g. swagger-cli validate) before loading.","Check the schema file path in the appsec config points to the correct, non-empty file."],"exampleFix":"// before (in spec)\n$ref: './components.yaml#/schemas/Pet'  # file not found at runtime\n\n// after\n$ref: '#/components/schemas/Pet'","handlingStrategy":"validation","validationCode":"// parse-check with an OpenAPI loader before handing bytes to LoadSchema\nloader := openapi3.NewLoader()\nif _, err := loader.LoadFromData([]byte(schema)); err != nil {\n    return fmt.Errorf(\"spec %q not parseable: %w\", ref, err)\n}","typeGuard":null,"tryCatchPattern":"if err := rv.LoadSchema(ref, schema, opts); err != nil {\n    if strings.Contains(err.Error(), \"failed to load schema\") {\n        log.Errorf(\"fix YAML/JSON or $refs in %s: %v\", ref, err)\n    }\n    return err\n}","preventionTips":["Run an OpenAPI linter in CI on every spec change","Avoid external $ref files, or ensure paths resolve from the crowdsec working directory","Lint YAML before deploying (yamllint)"],"tags":["openapi","yaml","parse-error","appsec"],"backgroundTag":"yaml-parse-error","analyzedSha":"909b5157986a2b2c2163300fdaef5ed01289f7d2","analyzedAt":"2026-09-06T12:27:26.012Z","contentChangedAt":"2026-09-06T12:27:26.012Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}