stride3d/stride · error · Exception

Failed to compile .

Error message

Failed to compile { Url }.

What it means

This is a final safety check: after all format conversion and height-type branches, if no Heightmap instance was produced the compiler throws 'Failed to compile {Url}'. It signals the heightmap asset pipeline produced nothing, usually because an earlier branch silently skipped creation or the texture had zero/invalid dimensions.

Solutions

1. Check build logs above this error for the format/height-type that failed to convert
2. Fix the source image format and re-import (see the unsupported-format error)
3. Re-create the heightmap asset from a valid 8-bit RGBA grayscale image
4. Verify the texture has non-zero width/height

Example fix

// before
var img = Image.Load("empty.png"); // 0x0 image
// after
var img = Image.Load("terrain_1024x1024_rgba8.png");

using var img = Image.Load(path);
if (img.PixelBuffer.Width == 0 || img.PixelBuffer.Height == 0)
    throw new InvalidOperationException($"Heightmap source {path} has zero dimensions");

When it happens

Trigger: DoCommandOverride completes every switch without assigning the local heightmap (e.g. unhandled combination of height type and pixel layout, or empty texture data), then the null check fires before assetManager.Save.

Common situations: Assets with mismatched configuration (unsupported format caught earlier but heightmap still null), zero-sized source images, or partially migrated assets from an older project.

Related errors

• Failed to find index buffer while building a convex hull.
• format is not supported.
• . should be greater than .
• height type is not supported.
• failed to scale .. to .. . Check HeightScale and…

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

Appendix: source

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

                                        ScaleToHeightRange(bytes, byte.MinValue, byte.MaxValue, heightRange, heightScale, commandContext);
                                    }

                                    heightmap = Heightmap.Create(size, heightType, heightRange, heightScale, bytes);
                                }
                                break;

                            default:
                                throw new Exception($"{ heightType } height type is not supported.");
                        }

                        commandContext.Logger.Info($"[{Url}] Convert Image(Format={ texImage.Format }, Width={ texImage.Width }, Height={ texImage.Height }) " +
                            $"to Heightmap(HeightType={ heightType }, MinHeight={ heightRange.X }, MaxHeight={ heightRange.Y }, HeightScale={ heightScale }, Size={ size }).");
                    }
                }

                if (heightmap == null)
                {
                    throw new Exception($"Failed to compile { Url }.");
                }

                assetManager.Save(Url, heightmap);

                return Task.FromResult(ResultStatus.Successful);
            }

            private void CalculateByteOrShortRange(Vector2 heightRage, float heightScale, out float min, out float max)
            {
                var minHeight = heightRage.X;
                var maxHeight = heightRage.Y;

                min = MathF.Round((minHeight / heightScale), MidpointRounding.AwayFromZero);
                max = MathF.Round((maxHeight / heightScale), MidpointRounding.AwayFromZero);

                if (heightScale < 0)
                {
                    min = (min * heightScale) < minHeight ? min - 1 : min;

View on GitHub (pinned to 96fad776d2)