Pandas左连接丢失右表列：为何缩减左表列数后恢复正常？

我遇到了Python pandas merge keyerror相关问题，现有解决方案无效。我需要计算某列部分行的梯度后合并回原DataFrame，代码如下：

import numpy as np
from scipy import signal

df = item_loc_df_dict['key_name']
prob_series = df['col1'].astype(float).values[5:(len(df['col1']) - 5)]
week_series = df['date_col'].values[5:(len(df['date_col']) - 5)]

gradient = np.square(np.gradient(prob_series))
win = signal.windows.hann(8)
gradients = signal.convolve(gradient, win, mode='same') / sum(win)
grad_df = pd.DataFrame({'date_col': week_series, 'peak_grads': gradients})

gradient_mean = np.mean(gradients)
gradient_std = np.std(gradients)
min_height = gradient_mean + gradient_std
peak_indices = signal.find_peaks(gradients, height=min_height)[0]
peak_grad_df = grad_df.iloc[peak_indices].reset_index(drop=True)

peak_grad_df['date_col'] = peak_grad_df['date_col'].astype('datetime64[ns]')
df['date_col'] = df['date_col'].astype('datetime64[ns]')

joined_df = df.merge(peak_grad_df, left_on=['date_col'], right_on=['date_col'], how='left')
joined_df['peak_grads'].fillna(0, inplace=True)

执行最后一行joined_df['peak_grads'].fillna(0, inplace=True)时出现KeyError: peak_grads，说明合并未包含右表列。原左表df约有200列，添加df = df[['date_col', 'col2', 'col3']]缩减列数后，KeyError消失，合并正常。请问为何只有缩减左表列数后合并才生效？

可能的原因分析 #

• 左表存在同名列：原左表有200列，可能已经存在peak_grads列（甚至列名带空格、不可见字符这类隐性重复）。Pandas合并时，若左右表有同名列（除了连接键），会自动给列名加后缀（比如peak_grads_x、peak_grads_y），此时直接访问peak_grads自然找不到。缩减列数后，这个重复列被排除，合并后peak_grads正常保留。
• 大列数引发的隐性异常：当DataFrame列数过多时，可能存在内存分配异常、部分列数据类型冲突（比如datetime精度不一致），导致合并过程中右表列未被正确添加。缩减列数后数据量变小，这类隐性问题被规避。
• 旧版Pandas的bug：某些旧版本Pandas在处理超大型列数的DataFrame合并时存在bug，列数减少后触发条件消失，合并恢复正常。

验证与解决建议 #

1. 检查重复列：执行print('peak_grads' in df.columns)，如果返回True，说明左表已有该列，合并后需访问带后缀的列（比如peak_grads_y）。
2. 清理列名：用df.columns = df.columns.str.strip()去除列名前后空格或不可见字符，再尝试合并。
3. 升级Pandas：执行pip install --upgrade pandas到最新稳定版，验证是否是版本bug导致。
4. 指定合并后缀：在merge时添加suffixes=('_left', '_right')，明确区分左右表的同名列，比如修改为joined_df['peak_grads_right'].fillna(0, inplace=True)。

内容的提问来源于stack exchange，提问作者gary69