Phần lớn thời gian “fix bug” không nằm ở sửa code mà ở tìm đúng nguyên nhân; bài này gom các lỗi Spring Boot hay gặp theo triệu chứng, kèm cách đọc log và cách sửa. Bốn lỗi trong bài là lỗi thật gặp khi chạy lab Spring Boot 4.0.3 trên JDK 21 (mvn test: 29 test, 28 pass, 1 skip vì máy không chạy được Docker). Đọc xong, bạn có một quy trình chẩn đoán thay vì đoán mò hay dán log cho AI.
Sơ đồ tóm tắt:
flowchart TD
S[Triệu chứng] --> Q{Loại lỗi?}
Q -->|stack trace| ST["Caused by cuối + dòng code mình"]
Q -->|không khởi động| AF["Đọc APPLICATION FAILED TO START"]
Q -->|LazyInitializationException| LZ["Lấy đủ trong service, trả DTO"]
Q -->|401| A1["Token thiếu/sai/hết hạn"]
Q -->|403| A3[Biết bạn nhưng không cho]
A3 -.->|"bẫy: handler Exception.class"| E5["403 thành 500"]
K["Dừng: SIGTERM trước, kill -9 cuối"]
1. Cách đọc log và stack trace
Ý chính: exception thật thường bị bọc nhiều lớp; nguyên nhân gốc nằm ở Caused by cuối cùng, còn chỗ cần sửa thường là dòng đầu tiên thuộc package của bạn.
Quy trình ba bước khi thấy một stack trace dài:
- Kéo xuống
Caused bycuối cùng: đó là lỗi gốc. Các lớp trên chỉ là framework bọc lại. - Trong đoạn đó, tìm dòng đầu tiên có package của bạn (ví dụ
dev.lab.hr). Đó là chỗ code của bạn gọi vào chỗ lỗi. - Đọc thông điệp đầy đủ, kể cả phần trong ngoặc vuông (tên bảng, tên constraint, id entity).
Với ứng dụng không khởi động được, Spring Boot in một khối riêng (do FailureAnalyzer tạo), có Description: và Action:. Ví dụ thật khi chạy hai bản lab cùng port:
***************************
APPLICATION FAILED TO START
***************************
Description:
Web server failed to start. Port 18081 was already in use.
2. Lỗi lúc khởi động
Ý chính: ba nhóm lỗi khởi động hay gặp nhất là trùng port, thiếu bean và cấu hình DataSource; cả ba đều có thông điệp rõ trong khối APPLICATION FAILED TO START.
Trùng port (“Port 8080 was already in use”): một process khác (thường là chính bản cũ của bạn chưa tắt) đang giữ port.
# macOS / Linux
lsof -i :8080 # xem PID và tên process
kill <PID> # SIGTERM: cho ứng dụng tắt êm
kill -9 <PID> # chỉ khi process không chịu tắt
# Windows
netstat -ano | findstr :8080
taskkill /PID <PID> /F
Muốn chạy song song nhiều bản (hay chạy test), dùng server.port=0 để chọn port ngẫu nhiên còn trống.
Thiếu bean (“Parameter 0 of constructor in X required a bean of type ‘Y’ that could not be found”). Ba nguyên nhân hay gặp:
- Class
Ynằm ngoài package của class@SpringBootApplication, nên component scan không thấy. Đưa vào package con. - Quên annotation (
@Service,@Repository), hoặc bean bị@Profile/@ConditionalOn...tắt. Ylà interface mà không có cài đặt nào là bean.
Circular dependency (“The dependencies of some of the beans in the application context form a cycle”): A cần B, B cần A. Từ Spring Boot 2.6, vòng phụ thuộc bị cấm mặc định. Đừng bật lại spring.main.allow-circular-references; tách phần dùng chung ra bean thứ ba hoặc dùng event. Chi tiết ở bài IoC và Dependency Injection.
“Failed to configure a DataSource: ‘url’ attribute is not specified”: có starter JPA mà chưa cấu hình spring.datasource.url và không có DB nhúng, hoặc file cấu hình của profile đang bật thiếu nó. Kiểm profile in ở log khởi động.
3. ClassNotFound, NoSuchMethodError và build cũ
Ý chính: lỗi lớp/method “không tồn tại” lúc chạy gần như luôn là do build cũ còn sót, hoặc hai version của một thư viện cùng nằm trên classpath.
ClassNotFoundExceptionsau khi đổi tên package: thư mụctarget/classescòn class cũ, IDE chưa biên dịch lại. Chạy./mvnw clean compile; trong VS Code dùng “Java: Clean Java Language Server Workspace”; trong IntelliJ reload Maven project.NoSuchMethodError/NoClassDefFoundErrorlúc chạy dù biên dịch được: code biên dịch với version A của thư viện, lúc chạy lại nạp version B. Xem cây dependency:
./mvnw dependency:tree -Dincludes=com.fasterxml.jackson.core
Sửa bằng cách bỏ version tự ghi tay để BOM của Spring Boot quản lý, hoặc <exclusion> bản lạ do thư viện khác kéo vào.
4. Lỗi JPA hay gặp
Ý chính: lỗi JPA khó vì nó xuất hiện ở chỗ khác chỗ gây ra: chạm proxy sau khi session đóng, hoặc SQL chạy sớm/muộn hơn bạn nghĩ.
4.1. LazyInitializationException (lỗi thật trong lab)
Test refresh token trả 500. Log:
org.hibernate.LazyInitializationException: Could not initialize proxy [dev.lab.hr.user.User#3] - no session
at dev.lab.hr.user.User$HibernateProxy.getRoles(Unknown Source)
Nguyên nhân: service rotate() có @Transactional trả về entity User (là proxy lazy). Controller gọi user.getRoles() sau khi transaction đã đóng. Lab đặt spring.jpa.open-in-view=false, nên không còn session nào để tải dữ liệu.
Cách sửa: lấy đủ dữ liệu bên trong transaction và trả về dữ liệu thuần (record), không trả entity:
public record Rotated(String email, List<String> roles, String rawToken) {}
@Transactional(noRollbackFor = InvalidRefreshTokenException.class)
public Rotated rotate(String rawToken) {
// ... kiểm token, revoke token cũ ...
User user = current.getUser();
String next = issueInFamily(user, current.getFamilyId());
var roles = user.getRoles().stream().map(r -> r.getName()).sorted().toList(); // còn trong transaction
return new Rotated(user.getEmail(), roles, next);
}
4.2. Lỗi unique ném ra sớm hơn mong đợi (lỗi thật trong lab)
Test kỳ vọng vi phạm unique constraint xảy ra lúc flush(), nhưng exception lại ném ngay ở save(). Lý do: entity dùng GenerationType.IDENTITY, id do DB sinh khi INSERT. Để trả về entity có id, Hibernate phải chạy INSERT ngay lúc save(), không gom đến lúc flush được.
// IDENTITY: save() đã chạy INSERT, nên assertion phải bọc chính lời gọi save
assertThatThrownBy(() -> permissions.saveAndFlush(new Permission("A2", "/api/v1/a", "GET", "X")))
.isInstanceOf(DataIntegrityViolationException.class);
Hệ quả thực tế: với IDENTITY, Hibernate không batch được INSERT. Cần insert hàng loạt thì cân nhắc SEQUENCE (PostgreSQL) với allocationSize lớn.
Thêm hai lỗi JPA/JSON: vòng lặp JSON và data.sql chạy trước bảng
Vòng lặp JSON vô hạn (StackOverflowError hoặc HttpMessageNotWritableException: Infinite recursion): controller trả entity có quan hệ hai chiều, User.company trỏ Company.users trỏ ngược User. Jackson đi vòng mãi. Thường đi kèm LazyInitializationException hoặc lộ trường nhạy cảm như password.
Sửa đúng: không trả entity ra API, trả DTO record chỉ chứa trường cần (UserResponse của lab không có password, roles là list tên). @JsonIgnore hay @JsonManagedReference chỉ là băng dán, vẫn để lộ cấu trúc DB ra hợp đồng API.
data.sql báo “Table not found”: Spring Boot chạy script SQL trước khi Hibernate tạo bảng bằng ddl-auto. Bật spring.jpa.defer-datasource-initialization=true để script chạy sau. Với DB không nhúng (MySQL, PostgreSQL), script chỉ chạy khi có spring.sql.init.mode=always. Production nên dùng Flyway thay vì cả hai (xem bài auto-configuration và vòng đời).
5. Lỗi bảo mật: 401, 403 và 403 thành 500
Ý chính: trong API dùng JWT, 401 nghĩa là chưa xác thực được (thiếu, sai chữ ký, hết hạn token), 403 là đã biết bạn là ai nhưng không có quyền. Đọc header và log security trước khi sửa code.
| Triệu chứng | Nghĩa | Kiểm gì |
|---|---|---|
401, có WWW-Authenticate: Bearer error="invalid_token" |
token hỏng, sai chữ ký, hết hạn, sai issuer | exp, iss, secret/khoá hai bên có giống nhau không, thuật toán |
401, chỉ WWW-Authenticate: Bearer |
không gửi token | header Authorization: Bearer ... có tới server không (proxy, CORS) |
| 403 | đã xác thực, thiếu quyền | authority thực tế có ROLE_ không, claim nào được đọc thành authority |
| 403 với POST dù đã đăng nhập | CSRF còn bật | chain cho API dùng Bearer header thì tắt CSRF cho /api/** |
Hai dòng 401 đầu là hành vi của entry point mặc định của resource server; entry point tự viết (như của lab) chỉ ghi Bearer, nên khi đó dựa vào log.
Bật log chi tiết để thấy filter nào từ chối và authority thực tế:
logging.level.org.springframework.security=TRACE
Lỗi hay gặp nhất với 403: token chứa "roles": ["ADMIN"] nhưng converter mặc định đọc claim scope và thêm tiền tố SCOPE_, nên hasRole('ADMIN') (tức ROLE_ADMIN) không bao giờ khớp. Cách đổi converter ở bài phân quyền RBAC và OAuth2; các bẫy của chính token ở bài xác thực và JWT.
CORS: Postman gọi được, trình duyệt báo “blocked by CORS policy”. Trình duyệt gửi request OPTIONS (preflight) trước; nếu security chặn preflight (401) hay thiếu header Access-Control-Allow-Origin, request thật không bao giờ được gửi. Cấu hình CORS trong Spring Security bằng http.cors(...) với origin cụ thể, không dùng * khi có cookie. Giải thích đầy đủ ở bài Web và HTTP.
6. Dùng debugger thay vì println
Ý chính: breakpoint cho bạn xem trạng thái thật ở đúng thời điểm lỗi; ba kỹ năng đáng học là breakpoint có điều kiện, evaluate expression và remote debug.
- Breakpoint dòng: chạy ứng dụng ở chế độ Debug trong IDE, dừng ở dòng nghi ngờ, xem biến, đi từng bước (step over, step into).
- Breakpoint có điều kiện: chỉ dừng khi
id == 42hoặcemail.contains("test"). Không phải bấm Continue hàng trăm lần trong vòng lặp. - Exception breakpoint: dừng ngay khi
LazyInitializationExceptionđược ném, kể cả khi framework bắt lại sau đó. - Evaluate expression: khi đang dừng, chạy thử biểu thức (
user.getRoles().size(),auth.getAuthorities()) để kiểm giả thuyết mà không sửa code. - Remote debug: gắn IDE vào ứng dụng chạy ngoài IDE (container, máy dev khác):
java -agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=*:5005 -jar app.jar
Rồi tạo cấu hình “Remote JVM Debug” trỏ tới port 5005. Không mở port này ở môi trường có dữ liệu thật: ai kết nối được là chạy được code tuỳ ý.
Quy trình chẩn đoán khi chưa biết bắt đầu từ đâu
- Tái hiện: viết một test (hoặc một lệnh
curl) cho ra lỗi mỗi lần chạy. Lỗi không tái hiện được thì chưa sửa được. Cả bốn lỗi của lab đều được bắt bởi test, không phải bởi bấm tay. - Khoanh vùng tầng: status code và log cho biết lỗi ở đâu. 401/403 trước controller là filter chain; 400 là binding/validation; 500 kèm stack trace JPA là tầng dữ liệu.
- Một giả thuyết, một thay đổi: đổi một thứ, chạy lại test. Đổi ba thứ cùng lúc thì không biết thứ nào có tác dụng.
- Kiểm lại bằng cách làm hỏng: như lab đã làm với handler
AccessDeniedException: bỏ bản sửa đi, thấy test đỏ lại, mới chắc đó là nguyên nhân. - Giữ lại test để lỗi không quay lại (regression test).
Khi nhờ AI hỗ trợ, đưa cho nó đúng ba thứ: đoạn code liên quan, thông điệp lỗi đầy đủ (kể cả Caused by), và điều bạn mong đợi so với điều xảy ra. Dán cả trăm dòng log không có code thì nó chỉ đoán.
Ghi nhớ
- Đọc được stack trace từ
Caused bycuối cùng và tìm được dòng thuộc code của mình. - Biết ba nguyên nhân của “required a bean that could not be found”.
- Giải thích được vì sao
LazyInitializationExceptionxảy ra và sửa mà không bật open-in-view. - Phân biệt được 401 và 403 trong API JWT, và biết vì sao
@PreAuthorizecó thể trả 500. - Biết dùng breakpoint có điều kiện, exception breakpoint và remote debug.
Câu hỏi phỏng vấn
Junior
Ứng dụng báo “Port 8080 was already in use”. Bạn làm gì?
Tìm process đang giữ port (lsof -i :8080 hoặc netstat -ano), tắt nó bằng SIGTERM, hoặc đổi server.port.
Thường đó là bản cũ của chính ứng dụng chưa tắt trong IDE. Chỉ dùng kill -9 khi process không chịu tắt, vì nó bỏ qua graceful shutdown.
401 và 403 khác nhau thế nào?
401: server chưa xác định được bạn là ai (thiếu, sai hoặc hết hạn token). 403: đã biết bạn là ai nhưng bạn không có quyền.
Với 401, client nên đăng nhập lại hoặc refresh token. Với 403, đăng nhập lại không giúp gì; cần được cấp quyền.
Mid
LazyInitializationException là gì và sửa thế nào?
Là lỗi khi chạm vào quan hệ lazy (proxy) sau khi session Hibernate đã đóng; sửa bằng cách tải đủ dữ liệu trong transaction và trả DTO.
Dùng JOIN FETCH, @EntityGraph hoặc map sang DTO ngay trong service. Bật open-in-view che được lỗi nhưng giữ connection suốt request và giấu N+1.
Ứng dụng không khởi động vì “required a bean of type X that could not be found”. Nguyên nhân có thể là gì?
Class X nằm ngoài package được component scan, thiếu annotation stereotype, hoặc bean bị tắt bởi profile/điều kiện.
Kiểm package của class @SpringBootApplication, annotation trên X, profile đang bật, và condition report (--debug) nếu X lẽ ra do auto-config tạo.
Endpoint có @PreAuthorize trả 500 thay vì 403. Vì sao?
Vì AccessDeniedException ném trong lời gọi controller bị handler @ExceptionHandler(Exception.class) trong @RestControllerAdvice bắt và trả 500.
Lỗi phân quyền ở filter chain không đi qua advice, còn method security thì có. Thêm handler riêng cho AccessDeniedException (ném lại hoặc trả 403).
NoSuchMethodError lúc chạy dù code biên dịch được. Bạn điều tra thế nào?
Đó là dấu hiệu hai version của một thư viện: biên dịch với bản này, chạy với bản khác. Xem mvn dependency:tree để tìm bản thừa.
Sửa bằng cách để BOM của Spring Boot quản lý version, bỏ version ghi tay, hoặc exclude dependency bắc cầu sai version. Sau đó clean để xoá class cũ.
Senior
Một lỗi chỉ xảy ra trên môi trường staging, không tái hiện được ở máy local. Bạn tiếp cận thế nào?
So sánh khác biệt môi trường trước (profile, biến môi trường, version, dữ liệu), thu thập bằng chứng từ log/trace, rồi tái hiện bằng test với điều kiện giống staging.
- Kiểm property thực tế qua
/actuator/envvà profile trong log khởi động. - Bật log chi tiết theo package trong thời gian ngắn qua
/actuator/loggers, không cần deploy lại. - Dùng trace id để nối log giữa các service.
- Remote debug chỉ khi môi trường không có dữ liệu thật và có kiểm soát truy cập.
- Tái hiện bằng Testcontainers với đúng version DB của staging.
Từ vựng tiếng Anh
| Term | Phát âm | Nghĩa | Ví dụ câu tiếng Anh dùng trong phỏng vấn |
|---|---|---|---|
| stack trace | /stæk treɪs/ | dấu vết ngăn xếp lời gọi | “I read the stack trace from the last Caused by.” |
| root cause | /ruːt kɔːz/ | nguyên nhân gốc | “The root cause was a lazy proxy touched after the transaction closed.” |
| reproduce | /ˌriː.prəˈduːs/ | tái hiện | “First I wrote a test that reproduces the bug every time.” |
| stale build | /steɪl bɪld/ | bản build cũ còn sót | “A stale build left old classes in target, so a clean fixed it.” |
| dependency conflict | /dɪˈpen.dən.si ˈkɑːn.flɪkt/ | xung đột version thư viện | “NoSuchMethodError usually points to a dependency conflict.” |
| lazy loading | /ˈleɪ.zi ˈloʊ.dɪŋ/ | tải dữ liệu khi cần | “Lazy loading fails outside the session.” |
| preflight request | /ˈpriː.flaɪt/ | request kiểm tra trước của CORS | “The browser sends an OPTIONS preflight before the real request.” |
| breakpoint | /ˈbreɪk.pɔɪnt/ | điểm dừng | “A conditional breakpoint stops only for the failing id.” |
| swallow an exception | /ˈswɑː.loʊ/ | nuốt exception | “The catch-all handler swallowed the AccessDeniedException.” |
| regression test | /rɪˈɡreʃ.ən test/ | test chống lỗi quay lại | “I kept the failing test as a regression test.” |
Ghi chép dựa trên tài liệu khoá học của Hỏi Dân IT, viết lại và bổ sung theo cách hiểu của mình.