Lỗi thường gặp trong pandas, NumPy, Matplotlib và cách sửa
Bài 13/13 · Chương 10
Giải nghĩa lỗi và cảnh báo
- 15 phút
- Cơ bản
- Python 3.14
- Cập nhật
Trong bài này · 42
Lỗi thường gặp trong pandas và NumPy được gom ở đây thành 30 mục, xếp theo việc bạn đang làm: tính trên mảng, đọc file, chọn cột, đổi kiểu, ghép bảng, xử lý thời gian, chạy code cũ. Mỗi mục có đoạn code sai, dòng cuối của thông báo lỗi mà thư viện thật sự in ra, nghĩa của dòng đó, cách sửa, và link về bài dạy kỹ đúng chỗ đó.
Cách tìm lỗi của bạn trên trang này
Khi chương trình báo lỗi, Python in một đoạn traceback. Dòng quan trọng nhất là dòng cuối: tên lỗi đứng trước dấu hai chấm, lời giải thích đứng sau. Lỗi của pandas thường có tên dài như pandas.errors.ParserError; phần sau dấu chấm cuối cùng là tên lớp. Hãy chép vài từ sau dấu hai chấm (như not in index), tìm chúng trên trang (Ctrl+F), rồi so đoạn code của mình với đoạn code sai của mục tìm được. Cách đọc cả đoạn traceback có ở bài traceback.
Các dòng cuối dưới đây chạy trên NumPy 2.4.6 và pandas 3.0.2, giống nhau trên Python 3.12, 3.13 và 3.14. Code viết cho pandas 2 có thể in câu khác, nhất là chữ object thay cho str; nhóm Code cũ trên mạng ở cuối trang gom các trường hợp đó. Tên file, tên cột và con số trong thông báo của bạn sẽ khác, phần còn lại thì giống.
Lỗi của Matplotlib ít khi dừng chương trình: chữ tiếng Việt thành ô vuông chỉ là một cảnh báo, trang glyph missing from font nói cách sửa.
Các mục theo tên lỗi:
KeyError: mục 9, 10, 12, 15
ValueError: mục 1, 3, 5, 14, 16, 17, 22, 23, 27
TypeError: mục 19, 21, 24, 26, 30
AttributeError: mục 11, 20, 28, 29
IndexError: mục 2, 13
FileNotFoundError: mục 6
UnicodeDecodeError: mục 8
ParserError, một dạng của ValueError: mục 7
IntCastingNaNError, một dạng của ValueError: mục 18
OutOfBoundsDatetime, một dạng của ValueError: mục 25
AxisError, một dạng của ValueError: mục 4
Mảng NumPy
Các lỗi này đến từ hình dạng và kiểu của mảng: số chiều, số phần tử mỗi chiều, kiểu phần tử.
1. Nhân hai mảng không hợp hình dạng
import numpy as np
doanh_thu = np.array([[120, 95, 143], [80, 110, 99]])
he_so = np.array([1.1, 0.9])
print(doanh_thu * he_so)
Dòng cuối của thông báo lỗi:
ValueError: operands could not be broadcast together with shapes (2,3) (2,)
Python gọi lỗi này là ValueError. Mảng 2 dòng 3 cột chỉ ghép được với mảng 3 phần tử theo chiều cuối; mảng 2 phần tử không khớp chiều nào.
Cách sửa: đổi he_so thành cột bằng he_so[:, None] để nhân theo từng dòng. Trang operands could not be broadcast giải thích cách đọc hai hình dạng. Ôn lại: broadcasting.
2. Dùng hai chỉ số cho mảng một chiều
import numpy as np
gia = np.array([45000, 32000, 29000])
print(gia[0, 1])
Dòng cuối của thông báo lỗi:
IndexError: too many indices for array: array is 1-dimensional, but 2 were indexed
Python gọi lỗi này là IndexError. Mảng chỉ có một chiều, nên chỉ nhận một chỉ số.
Cách sửa: lấy hai phần tử bằng một list chỉ số, gia[[0, 1]], hay một lát cắt gia[0:2]. Trang too many indices gom các dạng khác. Ôn lại: cắt lát mảng.
3. Tạo mảng từ các list dài ngắn khác nhau
import numpy as np
ban = np.array([[3, 5, 2], [4, 1]])
Dòng cuối của thông báo lỗi:
ValueError: setting an array element with a sequence. The requested array has an inhomogeneous shape after 1 dimensions. The detected shape was (2,) + inhomogeneous part.
Python gọi lỗi này là ValueError. Mảng NumPy cần mọi dòng cùng số phần tử; list thứ hai thiếu một phần tử.
Cách sửa: bổ sung phần tử còn thiếu, hay dùng np.nan cho ô chưa có số: [[3, 5, 2], [4, 1, np.nan]]. Ôn lại: tạo mảng NumPy.
4. Gom theo trục không có
import numpy as np
ban = np.array([3, 5, 2])
print(ban.sum(axis=1))
Dòng cuối của thông báo lỗi:
numpy.exceptions.AxisError: axis 1 is out of bounds for array of dimension 1
Python gọi lỗi này là AxisError, một dạng của ValueError. Mảng một chiều chỉ có trục 0.
Cách sửa: bỏ axis= hay dùng axis=0; kiểm số chiều bằng ban.ndim trước khi chọn trục. Ôn lại: trục axis.
5. Đổi mảng chuỗi có ô chữ sang số nguyên
import numpy as np
so_luong = np.array(["12", "x"])
print(so_luong.astype(int))
Dòng cuối của thông báo lỗi:
ValueError: invalid literal for int() with base 10: np.str_('x')
Python gọi lỗi này là ValueError. Ô 'x' không phải chữ số; NumPy in kiểu np.str_ của ô trong thông báo.
Cách sửa: sửa hay bỏ ô hỏng trước khi đổi kiểu; với bảng dữ liệu, pd.to_numeric(..., errors="coerce") đánh dấu ô hỏng thành NaN. Ôn lại: kiểu phần tử dtype.
Đọc file
Nhóm này dừng ngay ở dòng read_csv(), trước khi bảng có dòng nào.
6. Đọc file không có ở thư mục đang chạy
import pandas as pd
don = pd.read_csv("don_hang_thang_3.csv")
Dòng cuối của thông báo lỗi:
FileNotFoundError: [Errno 2] No such file or directory: 'don_hang_thang_3.csv'
Python gọi lỗi này là FileNotFoundError. Tên file trong nháy là đường dẫn Python đã thử; file không nằm ở thư mục chương trình đang chạy.
Cách sửa: kiểm tên file và đuôi file, hay viết đường dẫn đầy đủ tới file. Ôn lại: đọc file CSV.
7. Dòng có nhiều ô hơn dòng tiêu đề
import io
import pandas as pd
csv = "mon,gia\ntrà đào,45000\nbạc xỉu,32,000\n"
menu = pd.read_csv(io.StringIO(csv))
Dòng cuối của thông báo lỗi:
pandas.errors.ParserError: Error tokenizing data. C error: Expected 2 fields in line 3, saw 3
Python gọi lỗi này là ParserError, một dạng của ValueError. Dấu phẩy trong 32,000 bị đọc là ranh giới ô. Trang Error tokenizing data kể đủ các nguyên nhân.
Cách sửa: đặt ô có dấu phẩy trong nháy kép, hay khai sep= và skiprows= đúng với file. Trang error tokenizing data chỉ cách tìm dòng lệch. Ôn lại: các tham số của read_csv.
8. Đọc file lưu bằng bảng mã Windows
from pathlib import Path
import pandas as pd
Path("kh_win.csv").write_text("ma_kh,tinh\nKH0001,Cà Mau\n",
encoding="cp1258")
kh = pd.read_csv("kh_win.csv")
Dòng cuối của thông báo lỗi:
UnicodeDecodeError: 'utf-8' codec can't decode byte 0xe0 in position 19: invalid continuation byte
Python gọi lỗi này là UnicodeDecodeError. File được lưu bằng bảng mã cp1258, nơi chữ à là một byte 0xe0 đứng riêng.
Cách sửa: đọc lại với encoding="cp1258"; byte 0xff ở vị trí 0 thì là UTF-16. Trang UnicodeDecodeError khi read_csv có bảng tra theo byte. Ôn lại: đọc file CSV.
Chọn cột và dòng
Đây là nhóm người mới gặp nhiều nhất: tên cột, nhãn dòng và điều kiện lọc.
9. Gõ tên cột khác tên trong bảng
import pandas as pd
kh = pd.DataFrame({"ma_kh": ["KH0001"], "tinh": ["Huế"]})
print(kh["Tỉnh"])
Dòng cuối của thông báo lỗi:
KeyError: 'Tỉnh'
Python gọi lỗi này là KeyError. Bảng không có cột nào tên đúng 'Tỉnh', kể cả chữ hoa và dấu.
Cách sửa: in kh.columns.to_list() rồi gõ đúng tên. Trang KeyError khi chọn cột kể cả trường hợp khoảng trắng và BOM. Ôn lại: chọn cột.
10. Một tên trong list cột không có
import pandas as pd
kh = pd.DataFrame({"ma_kh": ["KH0001"], "tinh": ["Huế"]})
print(kh[["ma_kh", "Tinh"]])
Dòng cuối của thông báo lỗi:
KeyError: "['Tinh'] not in index"
Python gọi lỗi này là KeyError. Chọn bằng list cột thì thông báo kể mọi tên không tìm thấy.
Cách sửa: sửa từng tên trong list theo kh.columns. Ôn lại: chọn cột.
11. Chọn cột bằng dấu chấm khi tên có dấu cách
import pandas as pd
kh = pd.DataFrame({"ma_kh": ["KH0001"], "ho ten": ["Lan"]})
print(kh.ho_ten)
Dòng cuối của thông báo lỗi:
AttributeError: 'DataFrame' object has no attribute 'ho_ten'
Python gọi lỗi này là AttributeError. Cột tên là "ho ten", có dấu cách; cách chọn bằng dấu chấm chỉ dùng được với tên không có dấu cách, không trùng tên phương thức.
Cách sửa: chọn bằng ngoặc vuông: kh["ho ten"]. Ôn lại: chọn cột.
12. Lấy phần tử đầu của Series có nhãn chữ bằng s[0]
import pandas as pd
ton = pd.Series([12, 0, 7], index=["SP01", "SP02", "SP03"])
print(ton[0])
Dòng cuối của thông báo lỗi:
KeyError: 0
Python gọi lỗi này là KeyError. pandas 3 hiểu ton[0] là tìm nhãn 0, mà các nhãn là "SP01", "SP02", "SP03".
Cách sửa: lấy theo vị trí bằng ton.iloc[0], theo nhãn bằng ton.loc["SP01"]. Ôn lại: loc và iloc.
13. Lấy dòng theo vị trí vượt cuối bảng
import pandas as pd
don = pd.DataFrame({"ma_don": ["DH1024", "DH1025"]})
print(don.iloc[2])
Dòng cuối của thông báo lỗi:
IndexError: single positional indexer is out-of-bounds
Python gọi lỗi này là IndexError. Bảng có hai dòng, vị trí 0 và 1; vị trí 2 không có.
Cách sửa: kiểm len(don) trước, hay lấy dòng cuối bằng don.iloc[-1]. Ôn lại: loc và iloc.
14. Ghép hai điều kiện lọc bằng and
import pandas as pd
don = pd.DataFrame({"kenh": ["Web", "App"],
"tong": [250000, 420000]})
print(don[(don["tong"] > 300000) and (don["kenh"] == "App")])
Dòng cuối của thông báo lỗi:
ValueError: The truth value of a Series is ambiguous. Use a.empty, a.bool(), a.item(), a.any() or a.all().
Python gọi lỗi này là ValueError. and cần một giá trị đúng sai, mà mỗi điều kiện là cả một Series.
Cách sửa: dùng & thay cho and, | thay cho or, mỗi điều kiện trong ngoặc. Trang the truth value of a Series is ambiguous gom các dạng khác. Ôn lại: lọc dữ liệu.
15. Gom nhóm theo một cột không có
import pandas as pd
don = pd.DataFrame({"kenh": ["Web", "App"],
"tong": [250000, 420000]})
print(don.groupby("kenh")["doanh_thu"].sum())
Dòng cuối của thông báo lỗi:
KeyError: 'Column not found: doanh_thu'
Python gọi lỗi này là KeyError. Sau groupby(), cột chọn trong ngoặc vuông phải có trong bảng.
Cách sửa: chọn đúng cột "tong", hay tạo cột doanh_thu trước khi gom. Ôn lại: groupby.
Kiểu dữ liệu
Cột đọc từ file hay mang kiểu khác với điều bạn nghĩ: số thành chữ, số nguyên thành số thực.
16. astype(float) gặp cột tiền có chữ đ
import pandas as pd
gia = pd.Series(["195.000đ", "75.000đ"])
print(gia.astype(float))
Dòng cuối của thông báo lỗi:
ValueError: could not convert string to float: '195.000đ'
Python gọi lỗi này là ValueError. Dấu chấm hàng nghìn và chữ đ không phải một phần của con số.
Cách sửa: bỏ chúng bằng str.replace() rồi mới đổi kiểu. Trang could not convert string to float có cả trường hợp dấu phẩy thập phân. Ôn lại: pd.to_numeric().
17. to_numeric gặp ô gõ sai
import pandas as pd
gia = pd.Series(["120000", "98O000"])
print(pd.to_numeric(gia))
Dòng cuối của thông báo lỗi:
ValueError: Unable to parse string "98O000" at position 1
Python gọi lỗi này là ValueError. Ô ở vị trí 1 có chữ O thay cho số 0.
Cách sửa: thêm errors="coerce" để ô hỏng thành NaN, rồi in các ô đó ra để sửa. Ôn lại: pd.to_numeric().
18. Đổi cột có ô trống sang int
import pandas as pd
don = pd.DataFrame({"so_luong": [2, None, 3]})
don["so_luong"] = don["so_luong"].astype(int)
Dòng cuối của thông báo lỗi:
pandas.errors.IntCastingNaNError: Cannot convert non-finite values (NA or inf) to integer.Replace or remove non-finite values or cast to an integer typethat supports these values (e.g. 'Int64')
Python gọi lỗi này là IntCastingNaNError, một dạng của ValueError. Kiểu int không có chỗ cho ô thiếu.
Cách sửa: điền ô thiếu bằng fillna() trước, hay đổi sang "Int64" để giữ ô thiếu. Trang IntCastingNaNError so hai cách. Ôn lại: kiểu Int64.
19. Tính trung bình một cột số đọc thành chữ
import pandas as pd
don = pd.DataFrame({"tong": ["250000", "420000"]})
print(don["tong"].mean())
Dòng cuối của thông báo lỗi:
TypeError: Cannot perform reduction 'mean' with string dtype
Python gọi lỗi này là TypeError. Cột tong có kiểu str, nên không tính trung bình được.
Cách sửa: đổi kiểu trước bằng pd.to_numeric(don["tong"]); xem kiểu các cột bằng don.dtypes. Ôn lại: đổi kiểu bằng astype.
20. Dùng .str trên cột số
import pandas as pd
gia = pd.Series([45000, 32000])
print(gia.str.replace("0", ""))
Dòng cuối của thông báo lỗi:
AttributeError: Can only use .str accessor with string values, not integer. Did you mean: 'std'?
Python gọi lỗi này là AttributeError. .str chỉ có trên cột chữ; gợi ý 'std' của Python là một tên gần giống, không liên quan.
Cách sửa: đổi sang chữ trước bằng gia.astype(str), hay dùng phép toán số nếu cột vốn là số. Ôn lại: phương thức chuỗi .str.
21. Cộng cột chữ với cột số
import pandas as pd
don = pd.DataFrame({"ma": ["DH"], "so": [1024]})
print(don["ma"] + don["so"])
Dòng cuối của thông báo lỗi:
TypeError: can only concatenate str (not "int") to str
Python gọi lỗi này là TypeError. Nối chuỗi cần cả hai vế là chuỗi.
Cách sửa: đổi vế số sang chữ: don["ma"] + don["so"].astype(str). Ôn lại: đổi kiểu bằng astype.
Thêm cột và ghép bảng
Nhóm này xảy ra khi độ dài hay kiểu khóa của hai vế không khớp nhau.
22. Gán list thiếu phần tử vào cột mới
import pandas as pd
don = pd.DataFrame({"ma_don": ["DH1024", "DH1025", "DH1026"]})
don["phi_giao"] = [30000, 0]
Dòng cuối của thông báo lỗi:
ValueError: Length of values (2) does not match length of index (3)
Python gọi lỗi này là ValueError. List có 2 phần tử, bảng có 3 dòng.
Cách sửa: đưa đủ một giá trị cho mỗi dòng, hay gán một giá trị đơn. Trang length of values does not match length of index có cách gán theo index. Ôn lại: thêm cột.
23. Ghép khóa chuỗi với khóa số
import pandas as pd
dong = pd.DataFrame({"ma_sp": ["0045", "0007"]})
sp = pd.DataFrame({"ma_sp": [7, 45],
"ten_sp": ["Trà đào", "Bạc xỉu"]})
print(dong.merge(sp, on="ma_sp"))
Dòng cuối của thông báo lỗi:
ValueError: You are trying to merge on str and int64 columns for key 'ma_sp'. If you wish to proceed you should use pd.concat
Python gọi lỗi này là ValueError. Hai cột khóa khác kiểu: chuỗi "0045" và số 45.
Cách sửa: đổi khóa số sang chuỗi đủ độ dài: sp["ma_sp"].astype(str).str.zfill(4). Trang you are trying to merge on int64 and object columns (câu của pandas 2) kể cả bẫy thiếu zfill(). Ôn lại: kiểm tra merge bằng validate.
24. Đưa hai bảng vào concat mà không bọc trong list
import pandas as pd
a = pd.DataFrame({"x": [1]})
b = pd.DataFrame({"x": [2]})
print(pd.concat(a, b))
Dòng cuối của thông báo lỗi:
TypeError: concat() takes 1 positional argument but 2 were given
Python gọi lỗi này là TypeError. concat() nhận một list các bảng làm đối số đầu.
Cách sửa: bọc các bảng trong ngoặc vuông: pd.concat([a, b]). Ôn lại: nối bảng bằng concat.
Thời gian
Lỗi đọc ngày và gom theo thời gian; lỗi sai định dạng ngày có thông báo nhiều dòng, đọc ở trang riêng.
25. Đổi ngày năm 3026 sang nano giây
import pandas as pd
ngay = pd.to_datetime(pd.Series(["05/03/3026"]), format="%d/%m/%Y")
ngay.astype("datetime64[ns]")
Dòng cuối của thông báo lỗi:
pandas.errors.OutOfBoundsDatetime: Out of bounds nanosecond timestamp: 3026-03-05 00:00:00
Python gọi lỗi này là OutOfBoundsDatetime, một dạng của ValueError. Đơn vị nano giây chỉ chứa tới năm 2262, và năm 3026 gần như chắc là gõ nhầm.
Cách sửa: sửa năm trong dữ liệu; kiểm năm sau khi đọc bằng ngay.dt.year. Trang time data does not match format kể cả lỗi sai định dạng. Ôn lại: pd.to_datetime().
26. resample trên index chưa phải thời gian
import pandas as pd
ban = pd.Series([3, 5], index=["2026-01-05", "2026-02-05"])
print(ban.resample("ME").sum())
Dòng cuối của thông báo lỗi:
TypeError: Only valid with DatetimeIndex, TimedeltaIndex or PeriodIndex, but got an instance of 'Index'
Python gọi lỗi này là TypeError. Index là chuỗi ngày, chưa đổi sang kiểu thời gian.
Cách sửa: đổi index trước: ban.index = pd.to_datetime(ban.index). Ôn lại: resample.
27. Gom theo tháng bằng mã cũ "M"
import pandas as pd
ngay = pd.to_datetime(["2026-01-05", "2026-02-05"])
ban = pd.Series([3, 5], index=ngay)
print(ban.resample("M").sum())
Dòng cuối của thông báo lỗi:
ValueError: Invalid frequency: M. Failed to parse with error message: ValueError("'M' is no longer supported for offsets. Please use 'ME' instead.")
Python gọi lỗi này là ValueError. pandas 3 bỏ mã "M"; mã cuối tháng là "ME".
Cách sửa: đổi "M" thành "ME", "H" thành "h", "A" thành "YE". Ôn lại: resample.
Code cũ trên mạng
Code viết cho pandas 1 hay 2 hay gặp nhóm lỗi này: phương thức hay tham số đã bị bỏ ở pandas 2.0 hoặc 3.0.
28. Thêm dòng bằng df.append()
import pandas as pd
don = pd.DataFrame({"ma_don": ["DH1024"], "tong": [250000]})
don = don.append({"ma_don": "DH1025", "tong": 420000},
ignore_index=True)
Dòng cuối của thông báo lỗi:
AttributeError: 'DataFrame' object has no attribute 'append'
Python gọi lỗi này là AttributeError. DataFrame.append() đã bị bỏ từ pandas 2.0.
Cách sửa: viết lại bằng pd.concat([don, pd.DataFrame([dong_moi])], ignore_index=True). Trang 'DataFrame' object has no attribute 'append' có cả applymap(). Ôn lại: nối bảng bằng concat.
29. Áp hàm lên từng ô bằng applymap()
import pandas as pd
gia = pd.DataFrame({"gia_le": [45000, 32000]})
print(gia.applymap(lambda x: x // 1000))
Dòng cuối của thông báo lỗi:
AttributeError: 'DataFrame' object has no attribute 'applymap'
Python gọi lỗi này là AttributeError. applymap() đã đổi tên thành DataFrame.map().
Cách sửa: đổi tên lời gọi: gia.map(lambda x: x // 1000). Ôn lại: apply.
30. Điền xuôi bằng fillna(method="ffill")
import pandas as pd
ban = pd.Series([120.0, None, 95.0])
print(ban.fillna(method="ffill"))
Dòng cuối của thông báo lỗi:
TypeError: NDFrame.fillna() got an unexpected keyword argument 'method'
Python gọi lỗi này là TypeError. pandas 3 bỏ tham số method của fillna(); pandas 2.1 và 2.2 chỉ in FutureWarning.
Cách sửa: dùng ban.ffill() hay ban.bfill(). Trang FutureWarning trong pandas kể các cảnh báo cũ đã thành lỗi. Ôn lại: điền ô thiếu bằng fillna.
Câu hỏi thường gặp
Lỗi của tôi không có trong 30 lỗi này thì làm sao?
Đọc dòng cuối của thông báo để biết tên lỗi, rồi mở trang giải nghĩa của lớp lỗi đó, chẳng hạn trang về KeyError. Nếu tên lỗi bắt đầu bằng pandas.errors, chép nguyên câu sau dấu hai chấm để tìm: câu của pandas thường nói thẳng tham số nào sai.
Vì sao cùng một đoạn code, máy tôi báo lỗi còn bài trên mạng thì không?
Thường là do khác bản pandas. Bài viết cho pandas 1 hay 2 dùng những cách viết mà pandas 3 đã bỏ, như append() hay fillna(method=). In pd.__version__ để biết bản bạn đang chạy, rồi xem trang sửa code pandas cũ.
Có lỗi nào không báo gì mà vẫn sai không?
Có, và chúng nguy hiểm hơn lỗi có thông báo: ghép bảng ra 0 dòng vì khóa thiếu số 0 đầu, astype(int) cắt phần lẻ, đọc file sai bảng mã ra chữ lạ. Sau mỗi bước đọc, đổi kiểu hay ghép bảng, hãy in số dòng và vài dòng đầu để kiểm, như bài kiểm tra chất lượng dữ liệu. Lệnh gán hai bước như df[mask]["c"] = v cũng thuộc loại này trên pandas 3; trang SettingWithCopyWarning giải thích.
Chủ đề
Bài này có hữu ích?
Hỏi đáp
Tham vấn chuyên môn
Nhà sáng lập AIDev và VietPlatform · Thạc sĩ AI MSE
- Tốt nghiệp thủ khoa xuất sắc Thạc sĩ AI MSE.
- Đồng sáng lập, CTO E-University, SVOnline: số hóa 10+ đại học, 40.000+ sinh viên.
- Xây hệ thống AI cho doanh nghiệp tại VietPlatform.