What causes "Key [{0}] must be a registered key" in stride3d/stride?

Register the composed key with ParameterKeys.Add before using ComposeWith

stride3d/stride · error · ArgumentException

Key [ ] must be a registered key

Error message

Key [{0}] must be a registered key

What it means

ParameterKey.ComposeWith looks up the composed key name via FindByName; Stride requires all parameter keys to be registered in the ParameterKeys registry. When the composed name is not found, it throws ArgumentException stating the original key must be a registered key.

Solutions

Register the composed key with ParameterKeys.Add before using ComposeWith
Verify the exact key name string matches the registered name (case-sensitive)
Check that key registration code (often static initializers) actually runs before composition
Use TryFindByName to probe registration status when debugging

Example fix

// before
var composed = key.ComposeWith(suffixBuilder); // composed name never registered
// after
ParameterKeys.Add(new ParameterKey<UInt32>(composedName, "..."));
var composed = key.ComposeWith(suffixBuilder);

Defensive patterns

Strategy: try-catch

Validate before calling

var candidate = /* composed name */;
if (ParameterKeys.TryFindByName(candidate) == null)
    throw new InvalidOperationException($"Composed key '{candidate}' is not registered; call ParameterKeys.Add first");

Try / catch

try { var composed = key.ComposeWith(builder); } catch (ArgumentException ex) when (ex.Message.Contains("must be a registered key")) { // register missing key or fix name
    log.Warn($"Unregistered parameter key: {ex.Message}"); throw; }

Prevention

Register all parameter keys in static initializers that are guaranteed to run
Use ParameterKey helper classes so registration happens via type initializers
Verify key names with TryFindByName in debug builds
Keep key name generation in one place to avoid string drift

When it happens

Trigger: Calling ComposeWith (e.g. via key composition like 'Permutation' keys or macros) where the resulting composed key name has never been registered with ParameterKeys.Add, or the source key name passed isn't registered.

Common situations: Shader macro/composition keys not registered at startup, key name strings built dynamically that don't match registered keys, keys registered under a different name (typo/case mismatch), or running code before key registration happens.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

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

Appendix: source

Thrown at sources/engine/Stride.Foundation/Effects/ParameterKeys.cs:200

                    {
                        builder.Append('[');
                        builder.Append(composedKey.Indexer);
                        builder.Append(']');
                    }

                    result = ComposeWith(composedKey.Key, builder);
                    composedKeys.Add(composedKey, result);
                }
            }
            return result;
        }

        private static ParameterKey ComposeWith(ParameterKey key, StringBuilder builder)
        {
            var newKey = FindByName(builder.ToString());
            if (newKey == null)
            {
                throw new ArgumentException("Key [{0}] must be a registered key".ToFormat(key));
            }
            return newKey;
        }

        public static ParameterKey TryFindByName(string name)
        {
            if (name == null)
            {
                return null;
            }

            lock (keyByNames)
            {
                ParameterKey key;
                keyByNames.TryGetValue(name, out key);
                return key;
            }
        }

View on GitHub (pinned to 96fad776d2)