crowdsecurity/crowdsec · error

ref cannot be empty

Error message

ref cannot be empty

What it means

RequestValidator.LoadSchema loads an additional OpenAPI schema under a given ref. The ref is the key used to store and later look up the schema, so it must be a non-empty string; calling with an empty ref is rejected immediately.

Source

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

			}
			return fmt.Errorf("%s security scheme not supported", input.SecurityScheme.Type)
		default:
			if unsupportedPolicy == PolicyIgnore {
				return nil
			}
			return fmt.Errorf("unsupported security scheme type %s", input.SecurityScheme.Type)
		}
		if authTokenValue == "" {
			return errors.New("auth token is required but not provided")
		}

		return nil
	}
}

func (rv *RequestValidator) LoadSchema(ref string, schema string, opts *SchemaOptions) error {
	if ref == "" {
		return errors.New("ref cannot be empty")
	}
	rv.logger.Debugf("loading schema for ref %s", ref)

	if _, exists := rv.loaders[ref]; exists {
		return fmt.Errorf("attempting to load a new schema for existing ref %s", ref)
	}

	options := opts.withDefaults()
	if err := options.OnRouteNotFound.validate(); err != nil {
		return fmt.Errorf("on_route_not_found: %w", err)
	}
	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)
	}

View on GitHub (pinned to 909b515798)

Solutions

1. Provide a non-empty ref as the first argument to LoadSchema
2. Fix the appsec configuration so each extra schema entry has its name/ref key set
3. Validate the ref (strings.TrimSpace != "") before calling LoadSchema and fail with a clearer upstream error
4. Check env vars / templating used to build the ref aren't resolving to empty strings

Example fix

// before
v.LoadSchema(cfg.RefName, schemaData, opts) // RefName == ""
// after
if cfg.RefName == "" { return fmt.Errorf("schema ref missing in config") }
v.LoadSchema(cfg.RefName, schemaData, opts)

if strings.TrimSpace(ref) == "" { return errors.New("cannot load schema with empty ref") }

if err := rv.LoadSchema(ref, schema, opts); err != nil { if strings.Contains(err.Error(), "ref cannot be empty") { log.Error("schema entry missing ref/name in config") } }

When it happens

Trigger: Calling LoadSchema("", schema, opts) — programmatically or via loadAPISchema configuration that resolves to an empty ref (e.g. missing name/ref field in config or an empty map key).

Common situations: Config file entry for an extra schema missing its 'name'/'ref' key; ref computed from an env var or path that is empty; code refactoring that stopped populating the ref parameter.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• invalid schema name
• on_challenge_submit hooks are only valid in-band, not under
• max_body_size must be a positive integer
• invalid challenge master_secret: %w
• appsec rule name is empty for %s

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