Tải mã nguồn đồ án về không chạy được: 12 lỗi hay gặp và cách sửa

Tải một bản mã nguồn về rồi bấm chạy mà lên ngay là chuyện hiếm. Gần như luôn có vài lỗi môi trường, và gần như luôn là mười hai lỗi dưới đây. Sửa theo thứ tự, đừng nhảy cóc.

Trước khi sửa bất cứ gì: đọc file hướng dẫn

Bản mã nguồn tử tế nào cũng có README.md hoặc HUONG_DAN_CAI_DAT.docx ghi rõ phiên bản cần cài. Chín trong mười lỗi phía dưới là do chạy sai phiên bản so với bản mà tác giả dùng. Mở file đó trước, mất một phút, tiết kiệm cả buổi.

Nhóm Java / Spring Boot

1. UnsupportedClassVersionError: has been compiled by a more recent version of the Java Runtime

Máy bạn đang chạy JDK cũ hơn bản biên dịch. Kiểm tra java -version, đối chiếu với <java.version> trong pom.xml. Cài đúng bản rồi trỏ lại JAVA_HOME. Trong IntelliJ còn phải sửa thêm ở File → Project Structure → Project SDK, sửa mỗi biến môi trường là chưa đủ.

2. Failed to configure a DataSource: 'url' attribute is not specified

Thiếu cấu hình kết nối. Tìm file application.properties.example hoặc application-example.yml, đổi tên thành application.properties, điền tên cơ sở dữ liệu, tài khoản, mật khẩu MySQL của máy bạn.

3. Communications link failure hoặc Access denied for user 'root'@'localhost'

MySQL chưa bật, hoặc sai mật khẩu, hoặc sai cổng. Mặc định MySQL chạy cổng 3306; nếu bạn cài kèm XAMPP mà máy đã có MySQL riêng thì rất hay bị đụng cổng — đổi một trong hai sang 3307 rồi sửa lại chuỗi kết nối.

4. Maven tải mãi không xong hoặc Could not resolve dependencies

Mạng chặn hoặc kho tải hỏng. Chạy ./mvnw clean install -U để buộc tải lại. Vẫn hỏng thì xoá thư mục ~/.m2/repository của đúng thư viện lỗi rồi chạy lại.

Nhóm PHP / Laravel / XAMPP

5. XAMPP không bật được Apache — Port 80 in use

Trên Windows thường là do IIS hoặc ứng dụng gọi thoại chiếm cổng 80. Trong XAMPP bấm Config của Apache, sửa httpd.conf, đổi Listen 80 thành Listen 8080, rồi truy cập localhost:8080.

6. Trang trắng hoàn toàn, không báo lỗi gì

PHP đang ẩn lỗi. Mở php.ini, đặt display_errors = On, khởi động lại Apache. Có thông báo lỗi rồi mới sửa được, đoán mò không ra.

7. No application encryption key has been specified

Dự án Laravel thiếu khoá. Chạy lần lượt: cp .env.example .env, composer install, php artisan key:generate, php artisan migrate --seed. Bước cuối tạo bảng và dữ liệu mẫu — bỏ qua là đăng nhập không được vì chưa có tài khoản nào.

8. SQLSTATE[HY000] [1049] Unknown database

Chưa tạo cơ sở dữ liệu. Vào phpMyAdmin tạo một database rỗng đúng tên ghi trong .env, rồi nhập file .sql kèm theo dự án, hoặc chạy php artisan migrate.

Nhóm Node.js / React

9. npm install báo ERESOLVE unable to resolve dependency tree

Xung đột phiên bản thư viện. Thử npm install --legacy-peer-deps. Vẫn lỗi thì xoá node_modules và package-lock.json rồi cài lại. Nếu dự án dùng yarn thì phải dùng yarn, trộn hai trình quản lý gói là sinh lỗi lạ.

10. Error: Cannot find module dù đã cài xong

Thường do chạy sai thư mục. Dự án tách frontend và backend thì phải mở hai cửa sổ dòng lệnh, mỗi cửa sổ vào một thư mục và chạy riêng.

11. Frontend lên nhưng gọi API báo lỗi CORS hoặc Network Error

Backend chưa chạy, hoặc địa chỉ API trong frontend trỏ sai cổng. Tìm biến kiểu REACT_APP_API_URL hoặc VITE_API_URL trong .env, sửa cho khớp cổng backend đang chạy thật.

12. node-gyp lỗi, hoặc node-sass không biên dịch được

Sai phiên bản Node. Đây là lỗi phiên bản kinh điển: node-sass gắn chặt với từng bản Node. Cài nvm rồi chuyển về đúng bản ghi trong README, thường là Node 16 hoặc 18 với dự án cũ.

Quy tắc sửa lỗi để không mất cả buổi

Đọc dòng lỗi đầu tiên, không đọc dòng cuối. Ngăn xếp lỗi dài thì nguyên nhân gốc nằm ở đầu, phần sau chỉ là hệ quả.

Sửa một thứ một lần. Đổi ba thứ cùng lúc rồi hết lỗi thì bạn không biết cái nào có tác dụng, và lần sau lỗi lại thì lại mò từ đầu.

Chép nguyên văn dòng lỗi đi tìm. Bỏ phần đường dẫn riêng của máy bạn, giữ phần thông báo. Lỗi môi trường gần như luôn có người gặp trước.

Đừng sửa code khi lỗi là do môi trường. Rất nhiều bạn thấy lỗi kết nối cơ sở dữ liệu liền vào sửa hàm truy vấn. Code không sai, chỉ là MySQL chưa bật.

Khi nào nên nhờ hỗ trợ

Nếu đã qua hết danh sách trên mà vẫn không lên, thường là bản mã nguồn đó thiếu file — thiếu file .sql, thiếu thư mục cấu hình, hoặc thiếu tài khoản quản trị mặc định. Cái này bạn không tự đoán ra được.

Mọi bản mã nguồn trong danh mục đề tài của WebDoAn đều có file hướng dẫn cài đặt kèm theo và có hỗ trợ dựng chạy sau khi tải — vì một bản không chạy được thì không có giá trị gì cả. Cần một bản chạy đúng máy bạn, đúng đề giảng viên giao thì xem bảng giá để biết chi phí và thời gian.