What causes "schema definition must exist" in vectordotdev/vector?

Construct a fresh visitor per root schema so the eligible set matches the definitions

schema definition must exist

Error message

schema definition must exist

What it means

The unevaluated-properties flattening visitor looks up each eligible `$ref` in the definitions map and asserts the definition exists before inlining it into referrer schemas. The panic fires when an entry in `eligible_to_flatten` has no corresponding definition — the set and the definitions map are out of sync.

Solutions

Construct a fresh visitor per root schema so the eligible set matches the definitions
Order definition-removing visitors after the unevaluated-flattening visitor
Verify all workspace crates resolve to one consistent vector-config version
Reproduce with the offending component config and inspect the eligibility map vs definitions

Example fix

// before (shared visitor across schemas)
let mut visitor = DisallowUnevaluatedPropertiesVisitor::default();
for schema in schemas { visitor.visit_root_schema(schema); }
// after
for schema in schemas {
    DisallowUnevaluatedPropertiesVisitor::default().visit_root_schema(schema);
}

Defensive patterns

Strategy: validation

Validate before calling

fn eligible_refs_present(eligible: &HashMap<String, Vec<String>>, defs: &Map<String, Schema>) -> Result<(), String> {
    for name in eligible.keys() {
        if !defs.contains_key(name.as_str()) {
            return Err(format!("eligible-to-flatten ref missing: {name}"));
        }
    }
    Ok(())
}

Try / catch

let referenced = definitions.get(current_schema_ref).ok_or_else(||
    anyhow::anyhow!("flatten target {current_schema_ref} missing from definitions"))?;

Prevention

Create a fresh visitor per root schema; do not reuse cached eligibility maps
Run flattening before any visitor that prunes definitions
Add integration tests covering unevaluatedProperties across component configs

When it happens

Trigger: `visit_schema_object` processes a reference classified as eligible to flatten, but `definitions` no longer contains it because another visitor removed it or the eligibility analysis ran against a different root schema.

Common situations: Running the flatten visitor after a definition-pruning visitor; reusing a visitor instance (with cached eligibility sets) across multiple root schemas; version skew between vector-config crates.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

AI-assisted analysis of vectordotdev/vector@bdb87aeaa4 (2026-09-16). Data as JSON: /api/errors/3ab77ff71d24832d. Report an issue: GitHub.

Appendix: source

Thrown at lib/vector-config/src/schema/visitors/unevaluated.rs:79

        //
        // When a given schema reference (the actual target of `$ref`) is eligible for flattening in
        // a given schema (what we're currently visiting) then it means that this schema would,
        // based on its composition, lead to the schema reference either being marked or unmarked.
        //
        // We flatten the schema reference into this schema to avoid that from occurring, and we do
        // so based on whichever group of referrers -- the schemas which reference the particular
        // target schema -- is smaller, such that we do the minimum number of flattenings per target
        // schema, to keep the schema as small as we reasonably can.
        if let Some(reference) = schema.reference.as_ref() {
            let current_parent_schema_ref = self.get_current_schema_scope();

            if let Some(referrers) = self.eligible_to_flatten.get(reference)
                && referrers.contains(current_parent_schema_ref)
            {
                let current_schema_ref = get_cleaned_schema_reference(reference);
                let referenced_schema = definitions
                    .get(current_schema_ref)
                    .expect("schema definition must exist");

                debug!(
                    referent = current_schema_ref,
                    referrer = current_parent_schema_ref.as_ref(),
                    "Found eligible referent/referrer mapping."
                );

                if let Schema::Object(referenced_schema) = referenced_schema {
                    debug!(
                        referent = current_schema_ref,
                        referrer = current_parent_schema_ref.as_ref(),
                        "Flattening referent into referrer."
                    );

                    schema.reference = None;
                    schema.merge(referenced_schema);
                }
            }

View on GitHub (pinned to bdb87aeaa4)