dotnet/machinelearning · error · System.ArgumentNullException

Value cannot be null. (Parameter 'supplemetaryJoinColumnName

Error message

Value cannot be null. (Parameter 'supplemetaryJoinColumnNames')

What it means

Merge also requires the supplementary (right-side) join-column array to be non-null; when supplemetaryJoinColumnNames is null it throws ArgumentNullException(nameof(supplemetaryJoinColumnNames)) — 'Value cannot be null. (Parameter 'supplemetaryJoinColumnNames')'. Both sides of the merge must specify which columns form the join keys.

Source

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

        /// <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>();

            // Get occurrences of values in columns used for join in the retained and supplementary dataframes

View on GitHub (pinned to 7b76e69cf9)

Solutions

1. Pass a string[] of column names present in the supplementary DataFrame, e.g. new[]{"Id"}
2. If both sides share key names, supply the same array for both parameters
3. Guard with an argument check before invoking Merge
4. Catch ArgumentNullException at a boundary and log which side was null

Example fix

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

if (rightKeys == null || rightKeys.Length == 0) throw new InvalidOperationException("supplemetaryJoinColumnNames required");

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

When it happens

Trigger: Calling df.Merge(other, new[]{"Id"}, null) or any public Merge/Join path where the right-side join key array is null.

Common situations: Joining on the same-named keys and mistakenly passing null for the right side instead of repeating the array; dynamic key construction returned null; API misuse where left keys were provided but right keys forgotten.

Related errors

• Value cannot be null. (Parameter 'retainedJoinColumnNames')
• 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/06e3c5d9e297e7f0. Report an issue: GitHub.