stride3d/stride · error · Exception

failed to scale .. to .. . Check HeightScale and…

Error message

{ nameof(ScaleToHeightRange) } failed to scale { minT }..{ maxT } to { min }..{ max }. Check HeightScale and HeightRange are proper.

What it means

ScaleToHeightRange<T> computes the target byte/short range from HeightRange and HeightScale via CalculateByteOrShortRange, then verifies those target bounds lie inside the source data's actual min/max (minT..maxT). If the requested range falls outside what the data can represent, it throws, advising you to check HeightScale and HeightRange.

Solutions

1. Set HeightRange to the terrain's actual min/max heights (visible in the log line minT..maxT)
2. Reduce HeightScale so CalculateByteOrShortRange stays within the source data range
3. Disable ScaleToHeightRange if the data already fits the target type
4. Recompute terrain bounds and update the heightmap asset accordingly

Example fix

// before
heightmapAsset.HeightScale = 1000f;   // pushes target range outside data
heightmapAsset.HeightRange = new Vector2(0f, 50000f);
// after
heightmapAsset.HeightScale = 1f;
heightmapAsset.HeightRange = new Vector2(0f, 120f); // matches actual terrain

var (minT, maxT) = GetActualDataRange(floatHeights);
var scaledMin = heightRange.X / heightScale;
var scaledMax = heightRange.Y / heightScale;
if (scaledMin < minT || scaledMax > maxT)
    throw new InvalidOperationException($"HeightRange/HeightScale out of data range {minT}..{maxT}");

When it happens

Trigger: Scaling a float heightmap to a byte/short range where CalculateByteOrShortRange yields min/max outside the actual data range (minT..maxT) — e.g. HeightScale too large, or HeightRange values beyond what the quantized type can express from the data.

Common situations: HeightScale set inconsistently with the mesh's actual height extent, HeightRange manual values not matching the terrain's real min/max heights, or float source data spanning far beyond the intended byte/short bounds.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• format is not supported.
• . should be greater than .
• height type is not supported.
• Failed to compile .
• type is not supported.

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

Appendix: source

Thrown at sources/engine/Stride.Assets/Physics/HeightmapAssetCompiler.cs:309

            {
                float min;
                float max;

                var typeOfT = typeof(T);

                if (typeOfT == typeof(float))
                {
                    min = heightRange.X;
                    max = heightRange.Y;
                }
                else if (typeOfT == typeof(short) || typeOfT == typeof(byte))
                {
                    CalculateByteOrShortRange(heightRange, heightScale, out min, out max);

                    if (!MathUtil.IsInRange(min, minT, maxT) ||
                        !MathUtil.IsInRange(max, minT, maxT))
                    {
                        throw new Exception(
                            $"{ nameof(ScaleToHeightRange) } failed to scale { minT }..{ maxT } to { min }..{ max }. Check HeightScale and HeightRange are proper.");
                    }
                }
                else
                {
                    throw new NotSupportedException($"{ typeof(T[]) } type is not supported.");
                }

                commandContext?.Logger.Info($"[{Url}] ScaleToHeightRange : { minT }..{ maxT } -> { min }..{ max }");

                if (typeOfT == typeof(float))
                {
                    float[] floats = heights as float[];
                    for (var i = 0; i < floats.Length; ++i)
                    {
                        floats[i] = MathUtil.Clamp(MathUtil.Lerp(min, max, MathUtil.InverseLerp(minT, maxT, floats[i])), min, max);
                    }
                }

View on GitHub (pinned to 96fad776d2)