What causes "Only 1 unknown dimension is allowed" in dotnet/machinelearning?

Re-export the model fixing all but one dimension as static (e.g. batch dynamic only): torch.onnx.export with dynamic_axes limited to one axis, or set fixed values in ONNX export axes.

dotnet/machinelearning · error · ArgumentOutOfRangeException

Only 1 unknown dimension is allowed

Error message

Only 1 unknown dimension is allowed

What it means

OnnxTransform validates each model input's tensor shape at bind time. ONNX models may declare dimensions as 0 (unknown/dynamic), but ML.NET only supports exactly one dynamic dimension per input tensor; if more than one dimension equals 0 it throws ArgumentOutOfRangeException naming the offending input column. This keeps the inferred IDataView column shape concrete.

Source

Thrown at src/Microsoft.ML.OnnxTransformer/OnnxTransform.cs:526

            {

                _parent = parent;
                _inputColIndices = new int[_parent.Inputs.Length];
                _inputTensorShapes = new OnnxShape[_parent.Inputs.Length];
                _inputOnnxTypes = new Type[_parent.Inputs.Length];

                var model = _parent.Model;
                for (int i = 0; i < _parent.Inputs.Length; i++)
                {
                    var inputNodeInfo = model.ModelInfo.GetInput(_parent.Inputs[i]);

                    var shape = inputNodeInfo.Shape;

                    var inputShape = AdjustDimensions(inputNodeInfo.Shape);

                    // Only allow a single unkown size dimension
                    if (inputShape.Where(x => x == 0).Count() > 1)
                        throw new ArgumentOutOfRangeException(_parent.Inputs[i], "Only 1 unknown dimension is allowed");

                    _inputTensorShapes[i] = inputShape.ToList();
                    _inputOnnxTypes[i] = inputNodeInfo.TypeInOnnxRuntime;

                    var col = inputSchema.GetColumnOrNull(_parent.Inputs[i]);
                    if (!col.HasValue)
                        throw Host.ExceptSchemaMismatch(nameof(inputSchema), "input", _parent.Inputs[i]);

                    _inputColIndices[i] = col.Value.Index;

                    var type = inputSchema[_inputColIndices[i]].Type;
                    var vectorType = type as VectorDataViewType;

                    var itemType = type.GetItemType();
                    var nodeItemType = inputNodeInfo.DataViewType.GetItemType();
                    if (itemType != nodeItemType)
                    {
                        // If the ONNX model input node expects a type that mismatches with the type of the input IDataView column that is provided

View on GitHub (pinned to 7b76e69cf9)

Solutions

Re-export the model fixing all but one dimension as static (e.g. batch dynamic only): torch.onnx.export with dynamic_axes limited to one axis, or set fixed values in ONNX export axes.
Post-process the ONNX model to hard-code the extra dynamic dims (onnx package: load, set dim_param to a fixed value via tensor.shape, save).
Reshape/pad data so only one dimension varies and pin the others in the model.
Use a different model variant with static input sizes.

Example fix

// before: export with multiple dynamic axes
torch.onnx.export(model, x, 'm.onnx', dynamic_axes={'input': {0: 'batch', 1: 'seq'}})
// after: only one dynamic axis
torch.onnx.export(model, x, 'm.onnx', dynamic_axes={'input': {0: 'batch'}})

Defensive patterns

Strategy: validation

Validate before calling

// C#: inspect model inputs before ApplyOnnxModel
using var session = new InferenceSession(modelPath);
foreach (var input in session.InputMetadata)
{
    int unk = input.Value.Dimensions.Count(d => d == -1 || d == 0);
    if (unk > 1)
        throw new InvalidOperationException($"{input.Key} has {unk} dynamic dims; re-export with at most 1");
}

Prevention

Export ONNX models with only one dynamic axis (usually batch).
Run a schema smoke-test (pipeline.GetOutputSchema) before long training runs.
Pin model export settings in CI so dynamic axes don't regress.
Document each model's fixed input dimensions next to the model file.

When it happens

Trigger: Calling MLContext.Transforms.ApplyOnnxModel (or the OnnxScoringEstimator) with a model whose input node declares two or more symbolic/unknown dimensions (shape entries equal to 0) for any single input, e.g. a model with input shape [0, 0, H, W].

Common situations: Using dynamic-batch ONNX models exported from PyTorch/TensorFlow where both batch and a spatial axis are marked dynamic; exporting models with variable sequence length and variable batch; using a model trained/exported elsewhere with fully dynamic axes.

Understand the failure class

Background: Tensor shape mismatch errors ("must have shape", "expected shape ... got ..."): when tensor dimensions disagree with what an op or layer was told to expect — this error's family across 6 libraries.

Related errors

AI-assisted analysis of dotnet/machinelearning@7b76e69cf9 (2026-09-11). Data as JSON: /api/errors/d2905e08860c7771. Report an issue: GitHub.