{"record":{"id":"03bdda5134480654","repo":"bevyengine/bevy","slug":"flatdependencysort","errorCode":"FlatDependencySort","errorMessage":"Failed to topologically sort the flattened dependency graph: {0}","messagePattern":"Failed to topologically sort the flattened dependency graph: (.+?)","errorType":"error_code","errorClass":"ScheduleBuildError","httpStatus":null,"severity":"error","filePath":"crates/bevy_ecs/src/schedule/error.rs","lineNumber":30,"sourceCode":"        },\n        AmbiguousSystemConflictsWarning, ConflictingSystems, NodeId, ScheduleGraph, SystemKey,\n        SystemSetKey, SystemTypeSetAmbiguityError,\n    },\n    world::World,\n};\n\n/// Category of errors encountered during [`Schedule::initialize`](crate::schedule::Schedule::initialize).\n#[non_exhaustive]\n#[derive(Error, Debug)]\npub enum ScheduleBuildError {\n    /// Tried to topologically sort the hierarchy of system sets.\n    #[error(\"Failed to topologically sort the hierarchy of system sets: {0}\")]\n    HierarchySort(DiGraphToposortError<NodeId>),\n    /// Tried to topologically sort the dependency graph.\n    #[error(\"Failed to topologically sort the dependency graph: {0}\")]\n    DependencySort(DiGraphToposortError<NodeId>),\n    /// Tried to topologically sort the flattened dependency graph.\n    #[error(\"Failed to topologically sort the flattened dependency graph: {0}\")]\n    FlatDependencySort(DiGraphToposortError<SystemKey>),\n    /// Tried to order a system (set) relative to a system set it belongs to.\n    #[error(\"`{:?}` and `{:?}` have both `in_set` and `before`-`after` relationships (these might be transitive). This combination is unsolvable as a system cannot run before or after a set it belongs to.\", .0.0, .0.1)]\n    CrossDependency(#[from] DagCrossDependencyError<NodeId>),\n    /// Tried to order system sets that share systems.\n    #[error(\"`{:?}` and `{:?}` have a `before`-`after` relationship (which may be transitive) but share systems.\", .0.0, .0.1)]\n    SetsHaveOrderButIntersect(#[from] DagOverlappingGroupError<SystemSetKey>),\n    /// Tried to order a system (set) relative to all instances of some system function.\n    #[error(transparent)]\n    SystemTypeSetAmbiguity(#[from] SystemTypeSetAmbiguityError),\n    /// Tried to run a schedule before all of its systems have been initialized.\n    #[error(\"Tried to run a schedule before all of its systems have been initialized.\")]\n    Uninitialized,\n    /// A warning that was elevated to an error.\n    #[error(transparent)]\n    Elevated(#[from] ScheduleBuildWarning),\n}\n","sourceCodeStart":12,"sourceCodeEnd":48,"githubUrl":"https://github.com/bevyengine/bevy/blob/396ca727080776bd313bb892423b7d94e03b81b4/crates/bevy_ecs/src/schedule/error.rs#L12-L48","documentation":"After the hierarchy is applied, Bevy flattens set membership onto individual systems and topologically sorts that flattened graph. `FlatDependencySort` reports a cycle among `SystemKey`s — the individual edges were fine (or hidden) at set level, but once each system inherits its sets' orderings, the combined constraints on some system are contradictory.","triggerScenarios":"A system belonging to two ordered sets inheriting contradictory directions; ordering constraints between sets that expand into a loop over shared member systems; `.before`/`.after` on a set combined with member systems' own constraints closing a transitive cycle only visible after flattening.","commonSituations":"Systems placed in multiple organizational sets (feature set + phase set) where the sets are also ordered against each other; plugin sets that overlap and are ordered; refactors that move a system into a set that participates in an opposing chain.","solutions":["Identify the systems named by the error's SystemKeys and which of their set memberships contribute orderings; remove one membership or one ordering edge","Pull the contested system out of one of the ordered sets, or stop ordering those two sets against each other","Collapse duplicated organizational sets into one so each system has a single ordering source"],"exampleFix":"// before\napp.configure_sets(Update, (Combat.after(Physics),));\napp.add_systems(Update, sync.in_set(Physics).in_set(Combat)); // flattened cycle\n\n// after\napp.add_systems(Update, sync.in_set(Physics));","handlingStrategy":"try-catch","validationCode":"// Early-build the schedule during development to surface flattened cycles before runtime\nlet _ = schedule.initialize(&mut world); // inspect the Result in dev/test builds","typeGuard":null,"tryCatchPattern":"match schedule.initialize(&mut world) {\n    Err(ScheduleBuildError::FlatDependencySort(err)) => {\n        // SystemKey-level cycle: log err, then audit shared memberships of the involved systems\n    }\n    other => other.map(|_| ()),\n}","preventionTips":["Keep each system in one ordering-relevant set; use additional sets only for unordered grouping","Document which sets are ordered relative to which","Integration-test plugin combinations, since flattened cycles often appear only when plugins combine"],"tags":["bevy","ecs","schedule","ordering","cycle","topological-sort"],"backgroundTag":"dependency-cycle","analyzedSha":"396ca727080776bd313bb892423b7d94e03b81b4","analyzedAt":"2026-08-20T16:12:39.808Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}