dotnet/machinelearning · error · System.ArgumentNullException

Value cannot be null. (Parameter 'retainedJoinColumnNames')

Error message

Value cannot be null. (Parameter 'retainedJoinColumnNames')

What it means

The private Merge method in DataFrame.Join requires both join-key arrays to be non-null. When retainedJoinColumnNames is null it throws ArgumentNullException(nameof(retainedJoinColumnNames)), producing 'Value cannot be null. (Parameter 'retainedJoinColumnNames')'. The caller (public Merge/Join overloads) must supply the list of column names to join on for the retained DataFrame.

Source

Thrown at src/Microsoft.Data.Analysis/DataFrame.Join.cs:177

        /// <param name="other"></param> 
        /// <param name="leftJoinColumn"></param> 
        /// <param name="rightJoinColumn"></param> 
        /// <param name="leftSuffix"></param> 
        /// <param name="rightSuffix"></param> 
        /// <param name="joinAlgorithm"></param> 
        /// <returns></returns> 
        public DataFrame Merge<TKey>(DataFrame other, string leftJoinColumn, string rightJoinColumn, string leftSuffix = "_left", string rightSuffix = "_right", JoinAlgorithm joinAlgorithm = JoinAlgorithm.Left)
        {
            return Merge(other, new[] { leftJoinColumn }, new[] { rightJoinColumn }, leftSuffix, rightSuffix, joinAlgorithm);
        }

        private static HashSet<long> Merge(DataFrame retainedDataFrame, DataFrame supplementaryDataFrame,
            string[] retainedJoinColumnNames, string[] supplemetaryJoinColumnNames,
            out PrimitiveDataFrameColumn<long> retainedRowIndices, out PrimitiveDataFrameColumn<long> supplementaryRowIndices,
            bool isInner = false, bool calculateIntersection = false)
        {
            if (retainedJoinColumnNames == null)
                throw new ArgumentNullException(nameof(retainedJoinColumnNames));

            if (supplemetaryJoinColumnNames == null)
                throw new ArgumentNullException(nameof(supplemetaryJoinColumnNames));

            if (retainedJoinColumnNames.Length != supplemetaryJoinColumnNames.Length)
                throw new ArgumentException(Strings.MismatchedArrayLengths, nameof(retainedJoinColumnNames));

            Dictionary<long, ICollection<long>> occurrences = GetOccurences(retainedDataFrame, supplementaryDataFrame,
                retainedJoinColumnNames, supplemetaryJoinColumnNames, out HashSet<long> supplementaryJoinColumnsNullIndices);

            return PerformMerging(retainedDataFrame, retainedJoinColumnNames, occurrences, supplementaryJoinColumnsNullIndices,
                out retainedRowIndices, out supplementaryRowIndices, isInner, calculateIntersection);
        }

        private static Dictionary<long, ICollection<long>> GetOccurences(DataFrame retainedDataFrame, DataFrame supplementaryDataFrame,
            string[] retainedJoinColumnNames, string[] supplemetaryJoinColumnNames, out HashSet<long> supplementaryJoinColumnsNullIndices)
        {
            supplementaryJoinColumnsNullIndices = new HashSet<long>();

View on GitHub (pinned to 7b76e69cf9)

Solutions

1. Pass a non-empty string[] of column names present in the retained DataFrame for retainedJoinColumnNames
2. Compute the join keys before calling and assert they are not null
3. Catch ArgumentNullException and surface a clearer domain error in your app
4. Use the friendlier public Join overloads that derive join columns for you

Example fix

// before
df.Merge(other, null, new[] { "Id" });
// after
df.Merge(other, new[] { "Id" }, new[] { "Id" });

if (leftKeys == null || leftKeys.Length == 0) throw new InvalidOperationException("retainedJoinColumnNames required");

try { return df.Merge(other, leftKeys, rightKeys); } catch (ArgumentNullException ex) when (ex.ParamName == "retainedJoinColumnNames") { throw new ArgumentException("Left join keys must be provided", ex); }

When it happens

Trigger: Calling df.Merge(other, null, new[]{"key"}) (or a Join overload path) where the left/retained join-column array is null.

Common situations: Building join column names dynamically and the array ended up null instead of empty; misreading the Merge API signature and passing null for the left keys; refactoring joined columns away.

Related errors

• Value cannot be null. (Parameter 'supplemetaryJoinColumnName
• Value cannot be null. (Parameter 'other')
• {fieldType.Name}
• MismatchedColumnLengths
• Exception of type 'System.ArgumentException' was thrown.

AI-assisted analysis of dotnet/machinelearning@7b76e69cf9 (2026-09-11). Data as JSON: /api/errors/72bf3b354f8a80c2. Report an issue: GitHub.