BUG: ENH: Improve IntCastingNaNError message to suggest solutions for NaN in integer conversion

[ADITYA-kus]

Pandas version checks

• I have checked that this issue has not already been reported.

• I have confirmed this bug exists on the latest version of pandas.

• I have confirmed this bug exists on the main branch of pandas.

Reproducible Example

import pandas as pd
import numpy as np

print(pd.__version__)

df = pd.DataFrame({
    "roll": [12, 14, np.nan],
    "age": [20, np.nan, 30]
})

print("Original DataFrame:")
print(df)
print(f"Data types: {df.dtypes}")

print("\nAttempting to convert 'roll' column to int64:")
df['roll'] = df['roll'].astype('int64')
print(df)

Issue Description

Throwing an unhelpful error when converting float columns with NaN values to integer.

Original DataFrame:
roll age
0 12.0 20.0
1 14.0 NaN
2 NaN 30.0
Data types: roll float64
age float64
dtype: object

Attempting to convert 'roll' column to int64:
raise IntCastingNaNError(
"Cannot convert non-finite values (NA or inf) to integer"
)
pandas.errors.IntCastingNaNError: Cannot convert non-finite values (NA or inf) to integer

Expected Behavior

The error message should provide actionable guidance to help users understand how to handle NaN values when converting to integer types.

Installed Versions

python : 3.13.3
python-bits : 64
OS : Windows
OS-release : 11
Version : 10.0.26200
machine : AMD64
processor : Intel64 Family 6 Model 154 Stepping 3, GenuineIntel
byteorder : little
LC_ALL : None
LANG : en_US.UTF-8
LOCALE : English_India.1252

pandas : 2.2.3
numpy : 2.2.6
pytz : 2025.2
dateutil : 2.9.0.post0
pip : 25.2
Cython : None
sphinx : None
IPython : 9.3.0
adbc-driver-postgresql: None
adbc-driver-sqlite : None
bs4 : 4.13.4
blosc : None
bottleneck : None
dataframe-api-compat : None
fastparquet : None
fsspec : None
html5lib : None
hypothesis : None
gcsfs : None
jinja2 : 3.1.6
lxml.etree : 5.4.0
matplotlib : 3.10.3
numba : None
numexpr : None
odfpy : None
openpyxl : 3.1.5
pandas_gbq : None
psycopg2 : None
pymysql : None
pyarrow : 20.0.0
pyreadstat : None
pytest : None
python-calamine : None
pyxlsb : None
s3fs : None
scipy : 1.15.3
sqlalchemy : None
tables : None
tabulate : None
xarray : None
xlrd : None
xlsxwriter : None
zstandard : None
tzdata : 2025.2
qtpy : None
pyqt5 : None

[rhshadrach]

Thanks for the report. Can you propose what you'd like to see the error message be.

[ADITYA-kus]

Thanks for the quick response! Here's my proposed improved error message:

IntCastingNaNError: Cannot convert non-finite values (NA or inf) to integer.

Suggested solutions:
• Use .astype('Int64') for nullable integer type (supports missing values)
• Use .fillna(value) to replace missing values before conversion
• Use .dropna() to remove rows with missing values

Example usage:
df['column'] = df['column'].astype('Int64')
df['column'] = df['column'].fillna(0).astype('int64')
df = df.dropna().astype({'column': 'int64'})

[rhshadrach]

I see a few more, perhaps there are still others.

• One could also cast to different dtypes, e.g. int64[pyarrow] or float64 or ...
• One could avoid nans entering the data in the first place (e.g. join with how="inner" instead of the default how="left")
• A nan could be the result of invalid input data, and fixing the data could be the resolution.

The error message you have is already beyond what I think pandas should strive for in a concise error message. In this case, there are many different resolutions a user can do, it seems to me we should not attempt to enumerate them. I'm negative on this change.

cc @mroeschke for any thoughts.

[ADITYA-kus]

Thank you for the thoughtful feedback and for explaining the design philosophy around error messages. I appreciate your perspective about keeping them concise and avoiding enumeration of all possible solutions.

I completely understand that there are many ways to handle NaN values, and pandas shouldn't attempt to list them all. My main concern was that beginners often don't know about the existence of nullable integer types (Int64), which is the most pandas-idiomatic solution for this specific error.

If you'd be open to a more minimal approach, perhaps just mentioning nullable integers could help users discover this feature:

[mroeschke]

We could add "Replace or remove non-finite values or cast to an integer type that supports these values (e.g. 'Int64')"

[ADITYA-kus]

Thank you @mroeschke That's exactly the kind of improvement I was hoping for.

The suggested wording:
"Replace or remove non-finite values or cast to an integer type that supports these values (e.g. 'Int64')"

is perfect - it's concise, actionable, and points users toward the most relevant solution without being overwhelming. This would be incredibly helpful for beginners encountering this common issue.

I'm happy to work on implementing this change if you'd like.