0
# Pandas Errors and Warnings
1

2
The `pandas.errors` module provides comprehensive exception classes and warnings for error handling in pandas operations. These help developers identify and handle specific issues that can arise during data manipulation, file I/O, and analysis tasks.
3

4
## Core Imports
5

6
```python
7
import pandas as pd
8
from pandas import errors
9
from pandas.errors import (
10
    # Data Type Errors
11
    IntCastingNaNError,
12
    DtypeWarning,
13
    
14
    # Parsing and I/O Errors
15
    ParserError,
16
    ParserWarning,
17
    EmptyDataError,
18
    
19
    # Index and Data Structure Errors
20
    UnsortedIndexError,
21
    InvalidIndexError,
22
    IndexingError,
23
    DuplicateLabelError,
24
    
25
    # Performance and Operation Warnings
26
    PerformanceWarning,
27
    SettingWithCopyWarning,
28
    SettingWithCopyError,
29
    ChainedAssignmentError,
30
    
31
    # Computation and Analysis Errors
32
    DataError,
33
    SpecificationError,
34
    MergeError,
35
    
36
    # Frequency and Time Series Errors
37
    NullFrequencyError,
38
    OutOfBoundsDatetime,
39
    OutOfBoundsTimedelta,
40
    
41
    # Engine and Backend Errors
42
    NumbaUtilError,
43
    NumExprClobberingError,
44
    UndefinedVariableError,
45
    UnsupportedFunctionCall,
46
    
47
    # File Format Specific Errors
48
    DatabaseError,
49
    PossibleDataLossError,
50
    ClosedFileError,
51
    PyperclipException,
52
    PyperclipWindowsException,
53
    
54
    # Development and Internal Errors
55
    AbstractMethodError,
56
    InvalidComparison,
57
    LossySetitemError,
58
    NoBufferPresent,
59
)
60
```
61

62
## Data Type and Conversion Errors
63

64
### Type Casting Errors
65

66
**IntCastingNaNError** { .api }
67
```python
68
class IntCastingNaNError(ValueError)
69
```
70
Exception raised when converting an array with NaN values to integer type using `astype()`.
71

72
```python
73
# Example that raises IntCastingNaNError
74
import numpy as np
75
df = pd.DataFrame(np.array([[1, np.nan], [2, 3]]), dtype="i8")
76
# IntCastingNaNError: Cannot convert non-finite values (NA or inf) to integer
77
```
78

79
**DtypeWarning** { .api }
80
```python
81
class DtypeWarning(Warning)
82
```
83
Warning issued when `read_csv` or `read_table` encounter mixed data types in columns, typically when processing large files in chunks.
84

85
```python
86
# Mixed types in column trigger DtypeWarning
87
df = pd.DataFrame({'a': (['1'] * 100000 + ['X'] * 100000 + ['1'] * 100000)})
88
df.to_csv('mixed_types.csv', index=False)
89
df2 = pd.read_csv('mixed_types.csv')  # DtypeWarning: Columns (0) have mixed types
90
```
91

92
## Parsing and I/O Errors
93

94
### File Reading Errors
95

96
**ParserError** { .api }
97
```python
98
class ParserError(ValueError)
99
```
100
Generic exception for parsing errors in file reading functions like `read_csv` and `read_html`.
101

102
```python
103
# Malformed CSV data
104
data = '''a,b,c
105
cat,foo,bar
106
dog,foo,"baz'''
107
from io import StringIO
108
pd.read_csv(StringIO(data), skipfooter=1, engine='python')
109
# ParserError: ',' expected after '"'
110
```
111

112
**ParserWarning** { .api }
113
```python
114
class ParserWarning(Warning)
115
```
116
Warning when pandas falls back from the 'c' parser to 'python' parser due to unsupported options.
117

118
```python
119
# Using regex separator triggers ParserWarning
120
csv_data = '''a;b;c
121
1;1,8
122
1;2,1'''
123
df = pd.read_csv(StringIO(csv_data), sep='[;,]')  # ParserWarning: Falling back to 'python' engine
124
```
125

126
**EmptyDataError** { .api }
127
```python
128
class EmptyDataError(ValueError)
129
```
130
Exception raised when `read_csv` encounters empty data or headers.
131

132
```python
133
from io import StringIO
134
empty = StringIO()
135
pd.read_csv(empty)  # EmptyDataError: No columns to parse from file
136
```
137

138
## Index and Data Structure Errors
139

140
### Index Management Errors
141

142
**UnsortedIndexError** { .api }
143
```python
144
class UnsortedIndexError(KeyError)
145
```
146
Error when slicing a MultiIndex that hasn't been lexicographically sorted.
147

148
```python
149
# MultiIndex slicing without sorting
150
df = pd.DataFrame({"cat": [0, 0, 1, 1], "color": ["white", "white", "brown", "black"]})
151
df = df.set_index(["cat", "color"])
152
df.loc[(0, "black"):(1, "white")]  # UnsortedIndexError: Key length was greater than lexsort depth
153
```
154

155
**InvalidIndexError** { .api }
156
```python
157
class InvalidIndexError(Exception)
158
```
159
Exception for invalid index key usage, particularly with MultiIndex operations.
160

161
```python
162
# Invalid MultiIndex access
163
idx = pd.MultiIndex.from_product([["x", "y"], [0, 1]])
164
df = pd.DataFrame([[1, 1, 2, 2], [3, 3, 4, 4]], columns=idx)
165
df[:, 0]  # InvalidIndexError: (slice(None, None, None), 0)
166
```
167

168
**IndexingError** { .api }
169
```python
170
class IndexingError(Exception)
171
```
172
Exception for dimension mismatches and invalid indexing operations.
173

174
```python
175
df = pd.DataFrame({'A': [1, 1, 1]})
176
df.loc[..., ..., 'A']  # IndexingError: indexer may only contain one '...' entry
177
```
178

179
**DuplicateLabelError** { .api }
180
```python
181
class DuplicateLabelError(ValueError)
182
```
183
Error when operations would introduce duplicate labels on objects with `allows_duplicate_labels=False`.
184

185
```python
186
s = pd.Series([0, 1, 2], index=['a', 'b', 'c']).set_flags(allows_duplicate_labels=False)
187
s.reindex(['a', 'a', 'b'])  # DuplicateLabelError: Index has duplicates
188
```
189

190
## Performance and Copy Warnings
191

192
### Assignment and Copy Behavior
193

194
**PerformanceWarning** { .api }
195
```python
196
class PerformanceWarning(Warning)
197
```
198
Warning for operations that may impact performance, such as indexing past lexsort depth.
199

200
```python
201
# MultiIndex performance warning
202
df = pd.DataFrame({"jim": [0, 0, 1, 1], "joe": ["x", "x", "z", "y"]})
203
df = df.set_index(["jim", "joe"])
204
df.loc[(1, 'z')]  # PerformanceWarning: indexing past lexsort depth may impact performance
205
```
206

207
**SettingWithCopyWarning** { .api }
208
```python
209
class SettingWithCopyWarning(Warning)
210
```
211
Warning when setting values on a copied slice from a DataFrame (chained assignment).
212

213
```python
214
df = pd.DataFrame({'A': [1, 1, 1, 2, 2]})
215
df.loc[0:3]['A'] = 'a'  # SettingWithCopyWarning: A value is trying to be set on a copy
216
```
217

218
**SettingWithCopyError** { .api }
219
```python
220
class SettingWithCopyError(ValueError)
221
```
222
Exception version of SettingWithCopyWarning when `mode.chained_assignment` is set to 'raise'.
223

224
```python
225
pd.options.mode.chained_assignment = 'raise'
226
df = pd.DataFrame({'A': [1, 1, 1, 2, 2]})
227
df.loc[0:3]['A'] = 'a'  # SettingWithCopyError: A value is trying to be set on a copy
228
```
229

230
**ChainedAssignmentError** { .api }
231
```python
232
class ChainedAssignmentError(Warning)
233
```
234
Warning for chained assignment when Copy-on-Write mode is enabled, indicating the assignment won't update the original object.
235

236
```python
237
pd.options.mode.copy_on_write = True
238
df = pd.DataFrame({'A': [1, 1, 1, 2, 2]})
239
df["A"][0:3] = 10  # ChainedAssignmentError: chained assignment never works with Copy-on-Write
240
```
241

242
## Computation and Analysis Errors
243

244
### Data Operation Errors
245

246
**DataError** { .api }
247
```python
248
class DataError(Exception)
249
```
250
Exception for operations on non-numerical data where numerical data is required.
251

252
```python
253
ser = pd.Series(['a', 'b', 'c'])
254
ser.rolling(2).sum()  # DataError: No numeric types to aggregate
255
```
256

257
**SpecificationError** { .api }
258
```python
259
class SpecificationError(Exception)
260
```
261
Exception raised by `agg()` when aggregation functions are incorrectly specified.
262

263
```python
264
df = pd.DataFrame({'A': [1, 1, 1, 2, 2], 'B': range(5)})
265
df.groupby('A').B.agg({'foo': 'count'})  # SpecificationError: nested renamer is not supported
266
```
267

268
**MergeError** { .api }
269
```python
270
class MergeError(ValueError)
271
```
272
Exception during DataFrame merge operations, particularly validation failures.
273

274
```python
275
left = pd.DataFrame({"a": ["a", "b", "b", "d"], "b": ["cat", "dog", "weasel", "horse"]})
276
right = pd.DataFrame({"a": ["a", "b", "c", "d"], "c": ["meow", "bark", "chirp", "nay"]}).set_index("a")
277
left.join(right, on="a", validate="one_to_one")  # MergeError: Merge keys are not unique in left dataset
278
```
279

280
## Frequency and Time Series Errors
281

282
### Temporal Data Errors
283

284
**NullFrequencyError** { .api }
285
```python
286
class NullFrequencyError(ValueError)
287
```
288
Exception when a frequency cannot be null for time series operations like `shift()`.
289

290
```python
291
df = pd.DatetimeIndex(["2011-01-01 10:00", "2011-01-01"], freq=None)
292
df.shift(2)  # NullFrequencyError: Cannot shift with no freq
293
```
294

295
**OutOfBoundsDatetime** { .api }
296
```python
297
class OutOfBoundsDatetime(ValueError)
298
```
299
Exception for datetime values outside pandas' supported range (imported from pandas._libs.tslibs).
300

301
**OutOfBoundsTimedelta** { .api }
302
```python
303
class OutOfBoundsTimedelta(ValueError)
304
```
305
Exception for timedelta values outside pandas' supported range (imported from pandas._libs.tslibs).
306

307
## Engine and Backend Errors
308

309
### Computational Engine Errors
310

311
**NumbaUtilError** { .api }
312
```python
313
class NumbaUtilError(Exception)
314
```
315
Error for unsupported Numba engine routines in pandas operations.
316

317
```python
318
df = pd.DataFrame({"key": ["a", "a", "b", "b"], "data": [1, 2, 3, 4]})
319
def incorrect_function(x):
320
    return sum(x) * 2.7
321
df.groupby("key").agg(incorrect_function, engine="numba")  # NumbaUtilError: first 2 arguments must be ['values', 'index']
322
```
323

324
**NumExprClobberingError** { .api }
325
```python
326
class NumExprClobberingError(NameError)
327
```
328
Exception when using built-in numexpr names as variable names in `eval()` or `query()`.
329

330
```python
331
df = pd.DataFrame({'abs': [1, 1, 1]})
332
df.query("abs > 2")  # NumExprClobberingError: Variables overlap with builtins
333
```
334

335
**UndefinedVariableError** { .api }
336
```python
337
class UndefinedVariableError(NameError)
338
```
339
Exception for undefined variable names in `query()` or `eval()` expressions.
340

341
```python
342
df = pd.DataFrame({'A': [1, 1, 1]})
343
df.query("A > x")  # UndefinedVariableError: name 'x' is not defined
344
```
345

346
**UnsupportedFunctionCall** { .api }
347
```python
348
class UnsupportedFunctionCall(ValueError)
349
```
350
Exception for calling unsupported NumPy functions on pandas objects.
351

352
```python
353
df = pd.DataFrame({"A": [0, 0, 1, 1], "B": ["x", "x", "z", "y"]})
354
import numpy as np
355
np.cumsum(df.groupby(["A"]))  # UnsupportedFunctionCall: numpy operations not valid with groupby
356
```
357

358
## File Format Specific Errors
359

360
### Database and Storage Errors
361

362
**DatabaseError** { .api }
363
```python
364
class DatabaseError(OSError)
365
```
366
Error when executing SQL with bad syntax or database errors.
367

368
```python
369
from sqlite3 import connect
370
conn = connect(':memory:')
371
pd.read_sql('select * test', conn)  # DatabaseError: Execution failed on sql
372
```
373

374
**PossibleDataLossError** { .api }
375
```python
376
class PossibleDataLossError(Exception)
377
```
378
Exception when trying to open an HDFStore file that's already opened with a different mode.
379

380
**ClosedFileError** { .api }
381
```python
382
class ClosedFileError(Exception)
383
```
384
Exception when performing operations on a closed HDFStore file.
385

386
### Clipboard and System Integration
387

388
**PyperclipException** { .api }
389
```python
390
class PyperclipException(RuntimeError)
391
```
392
Exception for unsupported clipboard functionality in `to_clipboard()` and `read_clipboard()`.
393

394
**PyperclipWindowsException** { .api }
395
```python
396
class PyperclipWindowsException(PyperclipException)
397
```
398
Windows-specific exception when clipboard access is denied due to other processes.
399

400
## File Format Warnings
401

402
### HDF5 and Storage Warnings
403

404
**IncompatibilityWarning** { .api }
405
```python
406
class IncompatibilityWarning(Warning)
407
```
408
Warning for incompatible HDF5 file operations with where criteria.
409

410
**AttributeConflictWarning** { .api }
411
```python
412
class AttributeConflictWarning(Warning)
413
```
414
Warning when index attributes conflict during HDFStore operations.
415

416
### Stata File Warnings
417

418
**PossiblePrecisionLoss** { .api }
419
```python
420
class PossiblePrecisionLoss(Warning)
421
```
422
Warning when `to_stata()` converts int64 values to float64 due to range limitations.
423

424
**ValueLabelTypeMismatch** { .api }
425
```python
426
class ValueLabelTypeMismatch(Warning)
427
```
428
Warning when Stata export encounters non-string category values.
429

430
**InvalidColumnName** { .api }
431
```python
432
class InvalidColumnName(Warning)
433
```
434
Warning when column names are invalid Stata variables and need conversion.
435

436
**CategoricalConversionWarning** { .api }
437
```python
438
class CategoricalConversionWarning(Warning)
439
```
440
Warning when reading partially labeled Stata files with iterators.
441

442
### Style and Formatting Warnings
443

444
**CSSWarning** { .api }
445
```python
446
class CSSWarning(UserWarning)
447
```
448
Warning when CSS styling conversion fails or encounters unhandled formats.
449

450
```python
451
df = pd.DataFrame({'A': [1, 1, 1]})
452
df.style.applymap(lambda x: 'background-color: blueGreenRed;').to_excel('styled.xlsx')
453
# CSSWarning: Unhandled color format: 'blueGreenRed'
454
```
455

456
## Development and Internal Errors
457

458
### Abstract Method and Development Errors
459

460
**AbstractMethodError** { .api }
461
```python
462
class AbstractMethodError(NotImplementedError)
463
    def __init__(self, class_instance, methodtype: str = "method") -> None
464
```
465
Error for abstract methods that must be implemented in concrete classes. Supports different method types: 'method', 'classmethod', 'staticmethod', 'property'.
466

467
```python
468
class Foo:
469
    @classmethod
470
    def classmethod(cls):
471
        raise pd.errors.AbstractMethodError(cls, methodtype="classmethod")
472
    
473
    def method(self):
474
        raise pd.errors.AbstractMethodError(self)
475

476
Foo.classmethod()  # AbstractMethodError: This classmethod must be defined in the concrete class Foo
477
```
478

479
### Internal Implementation Errors
480

481
**InvalidComparison** { .api }
482
```python
483
class InvalidComparison(Exception)
484
```
485
Internal exception for invalid comparison operations (internal use only).
486

487
**LossySetitemError** { .api }
488
```python
489
class LossySetitemError(Exception)
490
```
491
Internal exception for non-lossless `__setitem__` operations on numpy arrays (internal use only).
492

493
**NoBufferPresent** { .api }
494
```python
495
class NoBufferPresent(Exception)
496
```
497
Internal exception signaling absence of requested buffer in `_get_data_buffer` (internal use only).
498

499
## Configuration Errors
500

501
### Options and Configuration
502

503
**OptionError** { .api }
504
```python
505
class OptionError(AttributeError)
506
```
507
Exception for pandas configuration option errors (imported from pandas._config.config).
508

509
**InvalidVersion** { .api }
510
```python
511
class InvalidVersion(ValueError)
512
```
513
Exception for invalid version strings (imported from pandas.util.version).
514

515
## Type Definitions
516

517
```python
518
# Error Categories
519
DataTypeError = Union[IntCastingNaNError, DtypeWarning]
520
ParsingError = Union[ParserError, ParserWarning, EmptyDataError]
521
IndexError = Union[UnsortedIndexError, InvalidIndexError, IndexingError, DuplicateLabelError]
522
CopyWarning = Union[PerformanceWarning, SettingWithCopyWarning, SettingWithCopyError, ChainedAssignmentError]
523
ComputationError = Union[DataError, SpecificationError, MergeError]
524
TimeSeriesError = Union[NullFrequencyError, OutOfBoundsDatetime, OutOfBoundsTimedelta]
525
EngineError = Union[NumbaUtilError, NumExprClobberingError, UndefinedVariableError, UnsupportedFunctionCall]
526
FileFormatError = Union[DatabaseError, PossibleDataLossError, ClosedFileError, PyperclipException]
527
FormatWarning = Union[IncompatibilityWarning, AttributeConflictWarning, PossiblePrecisionLoss, ValueLabelTypeMismatch, InvalidColumnName, CategoricalConversionWarning, CSSWarning]
528
DevelopmentError = Union[AbstractMethodError, InvalidComparison, LossySetitemError, NoBufferPresent]
529
ConfigurationError = Union[OptionError, InvalidVersion]
530

531
# All pandas errors and warnings
532
PandasError = Union[
533
    DataTypeError, ParsingError, IndexError, CopyWarning, ComputationError,
534
    TimeSeriesError, EngineError, FileFormatError, FormatWarning, 
535
    DevelopmentError, ConfigurationError
536
]
537
```
538

539
The pandas.errors module provides comprehensive error handling for all aspects of pandas operations, from basic data type conversions to complex multi-index operations and file I/O. Understanding these error types helps in writing robust pandas applications with proper exception handling and performance optimization.