Unity-Technologies/ml-agents · error · UnityAgentsException

{failedCheck.Message}

Error message

{failedCheck.Message}

What it means

ModelRunner validates the Sentis model with SentisModelParamLoader before creating a worker. If validation produces a failed check of type Error, the raw validation message is rethrown as a UnityAgentsException. This surfaces any model/agent mismatch the loader detected (wrong tensor shapes, sizes, or roles).

Source

Thrown at com.unity.ml-agents/Runtime/Inference/ModelRunner.cs:86

            {
#if SENTIS_VERBOSE
                m_Verbose = true;
#endif

                // TODO check w/Alex about verbosity level
                // D.logEnabled = m_Verbose;

                sentisModel = ModelLoader.Load(model);
                sentisModelInfo = new SentisModelInfo(sentisModel, deterministicInference);

                var failedCheck = SentisModelParamLoader.CheckModelVersion(
                    sentisModelInfo
                );
                if (failedCheck != null)
                {
                    if (failedCheck.CheckType == SentisModelParamLoader.FailedCheck.CheckTypeEnum.Error)
                    {
                        throw new UnityAgentsException(failedCheck.Message);
                    }
                }

                BackendType executionDevice;
                // WorkerFactory.Type executionDevice;
                switch (inferenceDevice)
                {
                    case InferenceDevice.ComputeShader:
                        executionDevice = BackendType.GPUCompute;
                        break;
                    case InferenceDevice.PixelShader:
                        executionDevice = BackendType.GPUPixel;
                        break;
                    case InferenceDevice.Burst:
                        executionDevice = BackendType.CPU;
                        break;
                    case InferenceDevice.Default: // fallthrough
                    default:

View on GitHub (pinned to 3ecb446f75)

Solutions

1. Read failedCheck.Message for the exact mismatch and align the Agent's Behavior Parameters (Vector Observation Space Size, Action Space) with the model's expected tensors
2. Re-export/retrain the model against the current environment definition (matching observation and action spaces)
3. Verify the model file is a valid Sentis-compatible .nn/.onnx exported by the same ml-agents version

Example fix

// before
Behavior Parameters: Vector Observation Space Size = 42, Continuous Actions = 2 (model expects 168 obs, 3 actions)
// after
Re-export the model or set Behavior Parameters to match the model: Vector Observation Space Size = 168, Continuous Actions = 3

var failedCheck = SentisModelParamLoader.CheckModel(sentisModel, sentisModelInfo);
if (failedCheck != null && failedCheck.CheckType == SentisModelParamLoader.FailedCheck.CheckTypeEnum.Error)
    throw new InvalidOperationException("Model incompatible: " + failedCheck.Message);

bool IsModelValid(SentisModelParamLoader.FailedCheck check) =>
    check == null || check.CheckType != SentisModelParamLoader.FailedCheck.CheckTypeEnum.Error;

try { var runner = new ModelRunner(model, behaviorParameters, inferenceDevice); }
catch (UnityAgentsException e)
{ Debug.LogError($"Model rejected: {e.Message}. Align Behavior Parameters with the trained model."); }

When it happens

Trigger: Instantiating ModelRunner with a .nn/.onnx model whose input/output tensors do not match the Agent's behavior parameters (vector observation size, action space, continuous vs discrete) — failedCheck.CheckType == Error.

Common situations: Swapping a trained model into an agent whose Behavior Parameters were changed after training; using a model trained for a different action space (discrete branch sizes vs continuous action size); loading a corrupted or wrong-format model file.

Related errors

• The BufferSensor was expecting an observation of size {m_Obs
• shape and dimensionProperties must have the same length.
• Index out of bounds, expected a number between 0 and {Length
• Enumerator not started.
• Enumerator has reached the end already.

AI-assisted analysis of Unity-Technologies/ml-agents@3ecb446f75 (2026-09-02). Data as JSON: /api/errors/b0803871a52e9347. Report an issue: GitHub.