What causes "Value cannot be null. (Parameter 'defines')" in Unity-Technologies/UnityCsReference?

Pass an empty array instead of null to clear defines: SetScriptingDefineSymbols(target, Array.Empty ()).

Unity-Technologies/UnityCsReference · error · ArgumentNullException

Value cannot be null. (Parameter 'defines')

Error message

Value cannot be null. (Parameter 'defines')

What it means

Thrown by PlayerSettings.SetScriptingDefineSymbols(NamedBuildTarget buildTarget, string[] defines) when the defines array is null. The method expects at minimum an empty array (to clear defines) — null is rejected because it ambiguously represents either 'no change' or 'clear all', and the API contract requires an explicit empty array for clearing.

Source

Thrown at Editor/Mono/PlayerSettings.bindings.cs:1094

            GetScriptingDefineSymbolsInternal(buildTarget.TargetName);
        public static void GetScriptingDefineSymbols(NamedBuildTarget buildTarget, out string[] defines) =>
            defines = ScriptingDefinesHelper.ConvertScriptingDefineStringToArray(GetScriptingDefineSymbols(buildTarget));

        // Set user-specified symbols for script compilation for the given build target group.
        public static void SetScriptingDefineSymbols(NamedBuildTarget buildTarget, string defines)
        {
            if (!string.IsNullOrEmpty(defines))
                defines = string.Join(";", ScriptingDefinesHelper.ConvertScriptingDefineStringToArray(defines));

            BuildProfileContext.UpdateScriptingDefineSymbolsInActivePlayerSettingsOverride(buildTarget, defines);

            SetScriptingDefineSymbolsInternal(buildTarget.TargetName, defines);
        }

        public static void SetScriptingDefineSymbols(NamedBuildTarget buildTarget, string[] defines)
        {
            if (defines == null)
                throw new ArgumentNullException(nameof(defines));

            SetScriptingDefineSymbols(buildTarget, ScriptingDefinesHelper.ConvertScriptingDefineArrayToString(defines));
        }

        [StaticAccessor("GetPlayerSettings().GetEditorOnlyForUpdate()")]
        [NativeMethod("SetUserScriptingDefineSymbols", ThrowsException = true)]
        private static extern void SetScriptingDefineSymbolsInternal(string buildTargetName, string defines);

        [StaticAccessor("GetPlayerSettings().GetEditorOnly()")]
        [NativeMethod("GetAdditionalCompilerArguments", ThrowsException = true)]
        private static extern string[] GetAdditionalCompilerArgumentsInternal(string buildTargetName);
        public static string[] GetAdditionalCompilerArguments(NamedBuildTarget buildTarget) =>
            GetAdditionalCompilerArgumentsInternal(buildTarget.TargetName);

        public static void SetAdditionalCompilerArguments(NamedBuildTarget buildTarget, string[] additionalCompilerArguments)
        {
            if (additionalCompilerArguments == null)
                throw new ArgumentNullException(nameof(additionalCompilerArguments));

View on GitHub (pinned to 225b0fbdb5)

Solutions

Pass an empty array instead of null to clear defines: SetScriptingDefineSymbols(target, Array.Empty<string>()).
Initialize the array before the conditional: var defines = Array.Empty<string>(); then populate conditionally.
Null-coalesce at the call site: SetScriptingDefineSymbols(target, defines ?? Array.Empty<string>()).

Example fix

// before
PlayerSettings.SetScriptingDefineSymbols(target, null);

// after
PlayerSettings.SetScriptingDefineSymbols(target, defines ?? Array.Empty<string>());

Defensive patterns

Strategy: validation

Validate before calling

PlayerSettings.SetScriptingDefineSymbols(target, defines ?? Array.Empty<string>());

Prevention

Pass Array.Empty<string>() instead of null to clear scripting defines.
Initialize define arrays before conditional code paths that might skip population.
Null-coalesce at the call site to guarantee a non-null array.

When it happens

Trigger: Calling SetScriptingDefineSymbols with a null string[] — e.g. when a deserialized or reflected value is null, or when a conditional code path skips array initialization. Passing an empty array (new string[0]) is valid and clears all defines.

Common situations: Editor scripts that conditionally build a defines array and pass null when the condition is unmet; deserialization of scripting define lists that are null; migrating from the string overload (which accepts null/empty) to the array overload.

Related errors

AI-assisted analysis of Unity-Technologies/UnityCsReference@225b0fbdb5 (2026-08-13). Data as JSON: /api/errors/353f891d2e94a7a8. Report an issue: GitHub.