vectordotdev/vector · error

referenced schema must exist in definitions

Error message

referenced schema must exist in definitions

What it means

After inlining a schema reference into all its usage sites, `visit_root_schema` removes the now-unused definition from `root.definitions` and asserts the entry exists. The panic fires if the definition was already removed — e.g. because inlining ran twice or the definition was deleted by another step between eligibility computation and removal.

Solutions

1. Apply the schema transformation pipeline exactly once per root schema
2. Check for duplicate visitor registration in the schema-generation pipeline
3. Use `remove().is_some()` defensive checks locally if you control a fork, but upstream the fix via `entry()`/idempotent removal
4. Regenerate the schema from scratch rather than re-visiting a mutated schema

Example fix

// before (re-visiting mutated schema)
visitor.visit_root_schema(&mut schema);
visitor.visit_root_schema(&mut schema);
// after
visitor.visit_root_schema(&mut schema);

fn assert_definitions_intact(root: &RootSchema, expected: &[&str]) -> Result<(), String> {
    for name in expected {
        if !root.definitions.contains_key(*name) {
            return Err(format!("definition missing before inline pass: {name}"));
        }
    }
    Ok(())
}

if root.definitions.remove(&schema_def_name).is_none() {
    tracing::warn!(referent = %schema_def_name, "definition already removed; skipping");
}

When it happens

Trigger: Running `visit_root_schema` (the single-ref inlining visitor) over a root schema where the target definition was already deleted: double invocation of the visitor, or another visitor in the pipeline removing definitions first.

Common situations: Applying the schema visitor pipeline twice to the same `RootSchema`; combining visitors that both prune definitions; unit-test fixtures calling the visitor repeatedly on shared state.

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

• schema definition must exist
• schema definition must exist
• schema reference should exist
• all-of subschemas must be present here
• Encountered schema with subschema validation that wasn't…

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

Appendix: source

Thrown at lib/vector-config/src/schema/visitors/inline_single.rs:82

            })
            .map(|s| s.as_ref().to_string())
            .collect::<HashSet<_>>();

        // Now run our own visitor logic, which will use the inline eligibility to determine if a
        // schema reference in a being-visited schema should be replaced inline with the original
        // referenced schema, in turn removing the schema definition.
        visit::visit_root_schema(self, root);

        // Now remove all of the definitions for schemas that were eligible for inlining.
        for schema_def_name in self.eligible_to_inline.drain() {
            debug!(
                referent = schema_def_name,
                "Removing schema definition from root schema."
            );

            root.definitions
                .remove(&schema_def_name)
                .expect("referenced schema must exist in definitions");
        }
    }

    fn visit_schema_object(
        &mut self,
        definitions: &mut Map<String, Schema>,
        schema: &mut SchemaObject,
    ) {
        // Recursively visit this schema first.
        visit::visit_schema_object(self, definitions, schema);

        // If this schema has a schema reference, see if it's in our inline eligibility map. If so,
        // we remove the referenced schema from the definitions, and then merge it into the current
        // schema, after removing the `$ref` field.
        if let Some(schema_ref) = schema.reference.as_ref().cloned() {
            let schema_ref = get_cleaned_schema_reference(&schema_ref);
            if self.eligible_to_inline.contains(schema_ref) {
                let referenced_schema = definitions

View on GitHub (pinned to bdb87aeaa4)