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.

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.

Appendix: 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)