crowdsecurity/crowdsec · error

invalid schema name

Error message

invalid schema name

What it means

ErrInvalidSchemaName is a sentinel error returned by the AppSec API validator when a request references an OpenAPI schema ref that is not present in the loaded openAPISchemas map (no schema was loaded for that ref). Callers can match it with errors.Is to distinguish 'unknown schema' from a validation failure.

Source

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

package apivalidation

import (
	"context"
	"errors"
	"fmt"
	"net/http"
	"strings"

	"github.com/getkin/kin-openapi/openapi3"
	"github.com/getkin/kin-openapi/openapi3filter"
	"github.com/getkin/kin-openapi/routers"
	legacyrouter "github.com/getkin/kin-openapi/routers/legacy"
	log "github.com/sirupsen/logrus"
)

var (
	ErrInvalidSchemaName = errors.New("invalid schema name")
)

// Policy controls what the validator does when it encounters a condition it
// cannot fully validate (unknown route, method not allowed for a matched
// path, security scheme type the WAF cannot enforce).
type Policy string

const (
	// PolicyDrop treats the condition as a validation failure.
	PolicyDrop Policy = "drop"
	// PolicyIgnore lets the request through as if the condition had passed.
	PolicyIgnore Policy = "ignore"
)

func (p Policy) validate() error {
	switch p {
	case PolicyDrop, PolicyIgnore:
		return nil

View on GitHub (pinned to 909b515798)

Solutions

1. Fix the ref/operationId in the AppSec config to match a schema present in the OpenAPI spec
2. Verify the OpenAPI spec file loads correctly and contains the referenced schema
3. Check logs for earlier spec-loading errors and correct the spec path/syntax
4. Match with errors.Is(err, api_validation.ErrInvalidSchemaName) in code to handle this case specifically

Example fix

// before (appsec config)
validate:
  schema: "MyRequestSchema"  # does not exist in the spec
// after
validate:
  schema: "CreateAlertRequest"  # matches a schema defined in the loaded spec

// verify the schema ref exists in the loaded spec at startup
if _, ok := schemas[refName]; !ok {
    return fmt.Errorf("schema %q not found in loaded OpenAPI spec", refName)
}

err := validator.ValidateRequest(req)
if errors.Is(err, api_validation.ErrInvalidSchemaName) {
    log.Errorf("config references unknown schema: %v", err)
    return
}

When it happens

Trigger: ValidateRequest resolving a schema ref (e.g. requestBody/parameter $ref or operationId mapping) when rv.openAPISchemas[ref] does not exist, reported as fmt.Errorf("%w: no schema loaded for ref %s", ErrInvalidSchemaName, ref).

Common situations: AppSec config pointing at an operationId/schema name that does not exist in the loaded OpenAPI spec; typo in the ref name; spec file failed to load partially so schemas were never registered; renamed schema after an upgrade.

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

• ref cannot be empty
• authorization header not found
• auth token is required but not provided
• on_challenge_submit hooks are only valid in-band, not under
• max_body_size must be a positive integer

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