# 8. DOTS Pitfalls
Part of [[DOTS]]. Previous: [[7. DOTS Profiling Quest and When Not to Use]].
> [!note] Verification status
> Items 1 and 12 are from the Entities 6.5 docs, and item 2 is from the Unity 6000.5 InstanceID-to-EntityId migration guide. Item 5 (`IJobEntity` isn't Burst by default) is from the IJobEntity page. The rest is general Jobs/ECS practice. **Code not compiled.**
1. **Following old tutorials.**
- `Entities.ForEach`, Aspects, `ConvertToEntity`, `[GenerateAuthoringComponent]` and `IConvertGameObjectToEntity` are deprecated or removed.
- Use `SystemAPI.Query`, `IJobEntity` and `Baker<T>`.
- Watch for `Translation`/`Rotation` components (pre-1.0). They're now `LocalTransform`.
2. **`InstanceID` ints in 6.5.** Starting in Unity 6.5, obsolete InstanceID APIs (`GetInstanceID` and similar) are compile errors. Migrate to the engine's 64-bit `EntityId`, which is the object ID, not the ECS `Entity`. Don't suppress the errors, because the IDs would truncate silently.
3. **Nothing appears.** The GameObjects aren't inside a **subscene**, or the subscene is closed and hasn't been baked.
4. **Source generator errors.** Systems and jobs must be `partial`.
5. **Slow jobs.** `[BurstCompile]` is missing on the `IJobEntity` struct, or on `ISystem` methods.
6. **"Structural changes not allowed" in jobs.** Use an `EntityCommandBuffer.ParallelWriter` with `[ChunkIndexInQuery]`, or enableable components.
7. **Leaks.** `TempJob`/`Persistent` containers need `Dispose()`. Dispose after jobs finish with `container.Dispose(handle)`.
8. **Hidden sync points.**
- `EntityManager` calls, `ToComponentDataArray` and `GetSingleton` on data that jobs write all force the main thread to wait.
- Batch them, or read them early in the frame.
9. **Single-threaded transform jobs.** All the transforms sit under one parent, and `IJobParallelForTransform` parallelizes per root (part 2, unverified on 6000.5).
10. **`Unity.Mathematics.Random` with seed 0** throws or misbehaves. Seeds must be non-zero. Use `Random.CreateFromIndex(i)` for per-entity streams.
11. **Prefab entity shows up in queries?** It doesn't, because entities with the `Prefab` tag are excluded by default. If you count one extra, you used `EntityQueryOptions.IncludePrefab`.
12. **Black or invisible entities.**
- Check the Entities Graphics requirements: URP **Forward+**, SRP Batcher, Linear color space.
- On Android, use **Vulkan**.
13. **Spatial-hash misses.** Cell size is smaller than the query radius (part 5).
14. **Racing with GameObjects.** MonoBehaviours read ECS data before systems ran this frame. Read in `LateUpdate`, or accept a one-frame lag (part 6).
15. **Using ECS for everything.** UI, audio, animation-heavy characters and one-off scripted events are easier on GameObjects (part 7).
## Sources
- Entities upgrade guide: https://docs.unity3d.com/Packages/
[email protected]/manual/upgrade-guide.html
- Migrate from InstanceID to EntityId: https://docs.unity3d.com/6000.5/Documentation/Manual/instanceid-to-entityid-migration.html
- IJobEntity: https://docs.unity3d.com/Packages/
[email protected]/manual/iterating-data-ijobentity.html
- Entities Graphics requirements: https://docs.unity3d.com/Packages/
[email protected]/manual/index.html