stride3d/stride · error · ArgumentException

The specified semantic name is too long. Usually it should…

Error message

The specified semantic name is too long. Usually it should not be longer than {MAX_SEMANTIC_NAME_LENGTH} bytes.

What it means

PipelineState validates that each input-element semantic name (HLSL semantic used in InputAssembler descriptions) fits within MAX_SEMANTIC_NAME_LENGTH bytes before converting it to the native D3D11 input layout description. A name longer than that limit triggers this ArgumentException with the offending parameter name attached.

Solutions

1. Shorten the semantic name in the input element description to a conventional HLSL semantic (POSITION, NORMAL, TEXCOORD0, etc.).
2. If the long name encodes data, move the extra information into a separate vertex attribute or constant buffer instead of the semantic.
3. Validate semantic name length in your pipeline description code before constructing the PipelineState.

Example fix

// before
new VertexElement("VERY_LONG_ENGINE_SPECIFIC_SEMANTIC_NAME_FOR_COLOR", PixelFormat.R8G8B8A8_UNorm)
// after
new VertexElement("COLOR", PixelFormat.R8G8B8A8_UNorm)

if (System.Text.Encoding.UTF8.GetByteCount(semanticName) > maxSemanticNameLength)
    throw new ArgumentException($"Semantic name '{semanticName}' exceeds {maxSemanticNameLength} bytes.");

static bool IsValidSemanticName(string s) => !string.IsNullOrEmpty(s) && System.Text.Encoding.UTF8.GetByteCount(s) <= 64;

try { pipelineState = BuildPipelineState(elements); }
catch (ArgumentException ex) when (ex.ParamName == "semanticName") { log.LogError($"Shorten semantic name: {ex.Message}"); }

When it happens

Trigger: Describing a PipelineState input element with a semantic name exceeding the internal length limit, typically via InputElement/VertexElement declarations passed to a PipelineState builder on the D3D11 backend.

Common situations: Hand-written or procedurally generated semantic names that are unusually long; code that prefixes semantic names with long debug namespaces; migrating shaders with verbose semantic naming conventions from other engines.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Element size must be greater than zero for structured…
• Cannot use .
• Could not find dependency
• Unexpected arguments
• A part Id cannot be empty.

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

Appendix: source

Thrown at sources/engine/Stride.Graphics/Direct3D11/PipelineState.Direct3D11.cs:840

                            releaseValue?.Invoke(valueComPtr);
                        }

                    reverse.Clear();
                    storage.Clear();
                    referenceCount.Clear();
                }
            }
        }

        #endregion

        #region Throw helpers

        [DoesNotReturn]
        [MethodImpl(MethodImplOptions.NoInlining)]
        private static void ThrowSemanticNameTooLong(string semanticName, [CallerArgumentExpression(nameof(semanticName))] string? paramName = null)
        {
            throw new ArgumentException($"The specified semantic name is too long. Usually it should not be longer than {MAX_SEMANTIC_NAME_LENGTH} bytes.", paramName);
        }

        #endregion
    }
}

#endif

View on GitHub (pinned to 96fad776d2)