stride3d/stride · error · ArgumentException

Please add a CharacterComponent to the entity containing…

Error message

Please add a CharacterComponent to the entity containing PlayerController!

What it means

PlayerController requires a CharacterComponent on the same entity to move the character via physics. In Start(), Entity.Get<CharacterComponent>() returns null, so the script throws this ArgumentException indicating the entity is missing the required character/physics component.

Solutions

1. Add a CharacterComponent to the same entity as the PlayerController.
2. Ensure the entity also has the collider/collider shape the CharacterComponent needs.
3. Confirm both NavigationComponent and CharacterComponent are on the PlayerController's entity.
4. Null-check Character before use if the scene is constructed programmatically.

Example fix

// before
entity.Add(new PlayerController());
// after
entity.Add(new CharacterComponent());
entity.Add(new PlayerController());

if (Entity.Get<CharacterComponent>() == null)
    throw new InvalidOperationException("Attach a CharacterComponent to the PlayerController entity before running.");

bool HasCharacter(Entity e) => e.Get<CharacterComponent>() != null;

try { playerController.Start(); } catch (ArgumentException ex) when (ex.Message.Contains("CharacterComponent")) { Log.Error("Scene misconfigured: add CharacterComponent"); }

When it happens

Trigger: Start() is called on an entity with PlayerController (and NavigationComponent) but no CharacterComponent attached.

Common situations: Setting up the navigation test scene without a CharacterComponent; attaching the character component to a child entity instead of the same one; renaming or removing the component after initial setup.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

• Please add a NavigationComponent to the entity containing…
• Url must be valid, assign null instead
• Custom strides is not supported with packed PixelFormats
• Overlapping update commands
• The collision object has been destroyed.

AI-assisted analysis of stride3d/stride@96fad776d2 (2026-09-14). Data as JSON: /api/errors/ad2e15b0f779cc27. Report an issue: GitHub.

Appendix: source

Thrown at sources/engine/Stride.Navigation.Tests/PlayerController.cs:73

        private Vector3 CurrentWaypoint => waypointIndex < pathToDestination.Count ? pathToDestination[waypointIndex] : Vector3.Zero;

        private MoveResult pendingResult;
        private TaskCompletionSource<MoveResult> taskCompletionSource;

        /// <summary>
        /// Called when the script is first initialized
        /// </summary>
        public override void Start()
        {
            base.Start();

            // Get the navigation component on the same entity as this script
            Navigation = Entity.Get<NavigationComponent>();
            if (Navigation == null) throw new ArgumentException("Please add a NavigationComponent to the entity containing PlayerController with the correct navigation mesh!");

            // Will search for an CharacterComponent within the same entity as this script
            Character = Entity.Get<CharacterComponent>();
            if (Character == null) throw new ArgumentException("Please add a CharacterComponent to the entity containing PlayerController!");
            
            moveDestination = SpawnPosition;
        }

        public void Reset()
        {
            pathToDestination.Clear();
            HaltMovement();
            moveDestination = SpawnPosition;
            Character.Teleport(SpawnPosition);
        }

        public override void Update()
        {
            if (!ReachedDestination)
            {
                var direction = CurrentWaypoint - Entity.Transform.WorldMatrix.TranslationVector;
                direction.Y = 0.0f;

View on GitHub (pinned to 96fad776d2)