{"record":{"id":"42926903137e6e40","repo":"sschmid/Entitas","slug":"expected-exactly-one-entity-in-collection-but-found-count","errorCode":null,"errorMessage":"Expected exactly one entity in collection but found {count}!","messagePattern":"Expected exactly one entity in collection but found (.+?)!","errorType":"exception","errorClass":"SingleEntityException","httpStatus":null,"severity":"error","filePath":"src/Entitas/Extensions/CollectionExtension.cs","lineNumber":14,"sourceCode":"using System.Collections.Generic;\nusing System.Linq;\n\nnamespace Entitas\n{\n    public static class CollectionExtension\n    {\n        /// Returns the only entity in the collection.\n        /// It will throw an exception if the collection doesn't have\n        /// exactly one entity.\n        public static Entity SingleEntity(this ICollection<Entity> collection)\n        {\n            if (collection.Count != 1)\n                throw new SingleEntityException(collection.Count);\n\n            return collection.First();\n        }\n\n        /// Returns the only entity in the collection.\n        /// It will throw an exception if the collection doesn't have\n        /// exactly one entity.\n        public static TEntity SingleEntity<TEntity>(this ICollection<TEntity> collection) where TEntity : Entity\n        {\n            if (collection.Count != 1)\n                throw new SingleEntityException(collection.Count);\n\n            return collection.First();\n        }\n    }\n\n    public class SingleEntityException : EntitasException\n    {","sourceCodeStart":1,"sourceCodeEnd":32,"githubUrl":"https://github.com/sschmid/Entitas/blob/37547d1bd280f3f1c1ef7edb44f2a206660fbfb4/src/Entitas/Extensions/CollectionExtension.cs#L1-L32","documentation":"Thrown by the SingleEntity() extension when the collection does not contain exactly one entity. It is a strict assertion helper: use it only where the entity count is guaranteed to be 1, otherwise it fails with SingleEntityException reporting the actual count.","triggerScenarios":"Calling collection.SingleEntity() when the group/collection has 0 entities (nothing matched) or more than 1 (multiple entities matched the same criteria).","commonSituations":"Assuming a singleton exists before it was created (first frames of the game); systems creating duplicate config/scoreboard entities; groups matched too broadly so several entities fit; calling before initialization finished.","solutions":["Check count first: if (collection.Count == 1) use SingleEntity, else handle 0/many","Use context.GetGroup(matcher).GetSingleEntity() which returns null for empty instead of throwing, or check its result for null","Enforce singleton creation in an initialization system so exactly one exists before consumers run","Narrow the matcher (Matcher.AllOf) so only the intended singleton matches"],"exampleFix":"// before\nvar score = context.GetGroup(ScoreMatcher).GetEntities().SingleEntity(); // throws when 0 or >1\n// after\nvar entities = context.GetGroup(ScoreMatcher).GetEntities();\nEntity scoreEntity = entities.Length == 1 ? entities.SingleEntity() : null;\nif (scoreEntity != null) {\n    // use scoreEntity\n}","handlingStrategy":"validation","validationCode":"var es = group.GetEntities();\nif (es.Length == 1) { var e = es.SingleEntity(); }","typeGuard":"bool HasSingleEntity(ICollection<Entity> c) => c.Count == 1;","tryCatchPattern":"try { var e = collection.SingleEntity(); }\ncatch (SingleEntityException ex) { Debug.LogWarning($\"expected 1 entity: {ex.Message}\"); }","preventionTips":["Prefer group.GetSingleEntity() (returns null on empty) over SingleEntity()","Check collection.Count == 1 before calling SingleEntity","Enforce singleton entity creation in an initialize system","Tighten matchers so only the intended singleton qualifies"],"tags":["csharp","entitas","collection","singleton"],"backgroundTag":"empty-result-set","analyzedSha":"37547d1bd280f3f1c1ef7edb44f2a206660fbfb4","analyzedAt":"2026-09-14T00:26:23.246Z","contentChangedAt":"2026-09-14T00:26:23.246Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}