sschmid/Entitas · error · ContextEntityIndexDoesNotExistException

ContextEntityIndexDoesNotExistException(this, name)

Error message

ContextEntityIndexDoesNotExistException(this, name)

What it means

GetEntityIndex looks up an IEntityIndex by name in the context's registry and throws when no index was registered under that name — the requested index simply does not exist (yet).

Solutions

Ensure AddEntityIndex for that name runs before GetEntityIndex (fix system init order)
Verify the exact index name string and that you're on the same context instance
Use TryGetEntityIndex / HasEntityIndex-style check if available, or wrap in a check

Example fix

// before
var idx = context.GetEntityIndex("UserById"); // throws if never added
// after
if (context.GetEntityIndex("UserById") is var idx && idx != null) { /* use */ }
else context.AddEntityIndex(new PrimaryEntityIndex<Entity, string>("UserById", ...));

Defensive patterns

Strategy: try-catch

Validate before calling

// ensure index exists before use
context.AddEntityIndex(new PrimaryEntityIndex<Entity, string>("UserById", e => e.id));
var idx = context.GetEntityIndex("UserById");

Try / catch

IEntityIndex idx;
try { idx = context.GetEntityIndex("UserById"); }
catch { throw new InvalidOperationException("Index 'UserById' not registered — initialize indexes before use"); }

Prevention

Register all indexes in a single init step that runs first
Centralize index name constants
Verify same context instance when sharing across systems

When it happens

Trigger: Calling context.GetEntityIndex("MyIndex") before AddEntityIndex was called for that name, or with a typo'd/renamed index name.

Common situations: Querying an index from a different context than the one it was added to, system execution order where the consumer runs before the initializer registers indexes, and index name refactors.

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 sschmid/Entitas@37547d1bd2 (2026-09-14). Data as JSON: /api/errors/d334d9941cf1ac2c. Report an issue: GitHub.

Appendix: source

Thrown at src/Entitas/Context/Context.cs:287

            return group;
        }

        /// Adds the IEntityIndex for the specified name.
        /// There can only be one IEntityIndex per name.
        public void AddEntityIndex(IEntityIndex entityIndex)
        {
            if (_entityIndexes.ContainsKey(entityIndex.Name))
                throw new ContextEntityIndexDoesAlreadyExistException(this, entityIndex.Name);

            _entityIndexes.Add(entityIndex.Name, entityIndex);
        }

        /// Gets the IEntityIndex for the specified name.
        public IEntityIndex GetEntityIndex(string name)
        {
            if (!_entityIndexes.TryGetValue(name, out var entityIndex))
                throw new ContextEntityIndexDoesNotExistException(this, name);

            return entityIndex;
        }

        /// Resets the creationIndex back to 0.
        public void ResetCreationIndex() => _creationIndex = 0;

        /// Clears the componentPool at the specified index.
        public void ClearComponentPool(int index) => _componentPools[index]?.Clear();

        /// Clears all componentPools.
        public void ClearComponentPools()
        {
            for (var i = 0; i < _componentPools.Length; i++)
                ClearComponentPool(i);
        }

        /// Resets the context (destroys all entities and

View on GitHub (pinned to 37547d1bd2)