Ralat HTTP 500 dalam Lucee: cara baca stack trace

Ralat HTTP 500 dalam Lucee: cara baca stack trace

Penulis: Thalhah · Tarikh: 3 Oktober 2026

Ralat HTTP 500 bermaksud templat CFML anda gagal sebelum ia sempat menghasilkan halaman. Lucee tidak menyembunyikan puncanya, ia mencetak keseluruhan rantaian ralat pada halaman kuning yang sama: jenis ralat, mesej ringkas, fail dan baris yang gagal, serta timbunan Java yang lengkap. Artikel ini mengajar anda membaca halaman itu sampai punca sebenar, menangkap ralat dengan cftry dan cfcatch, dan mencatatnya ke log, supaya anda tidak lagi meneka. Semua mesej ralat di bawah dicetuskan dan ditangkap secara langsung dalam Lucee 7.1, bukan dipetik daripada teori.

Apa Sebenarnya Ralat HTTP 500

Kod status 500 ialah jawapan generik pelayan yang bermaksud "ralat dalaman pelayan". Dalam Lucee, ia hampir selalu berpunca daripada kod CFML yang gagal: ralat sintaks semasa kompil, fungsi yang tidak wujud, kunci struct yang tiada, atau datasource yang tidak dapat disambung. Pelayar hanya melihat 500 dan teks kosong, tetapi anda sebagai pembangun melihat halaman ralat penuh yang menyimpan semua petunjuk. Kunci untuk menyelesaikan ralat dengan cepat ialah berhenti membaca mesej pertama sahaja dan mula membaca keseluruhan halaman secara berlapis.

Struktur Halaman Ralat Lucee

Halaman ralat Lucee disusun dalam beberapa medan, dan memahami susunannya ialah separuh daripada kerja. Baris tajuk menyebut versi enjin dan jenis ralat dalam kurungan, contohnya Error (template) untuk ralat kompil templat, Error (expression) untuk ralat ungkapan, dan Error (database) untuk ralat pangkalan data. Di bawahnya datang medan berikut:

• Message ialah ringkasan satu baris tentang apa yang gagal.
• Detail muncul pada sesetengah jenis ralat dan memberi konteks tambahan. Pada ralat datasource, contohnya, ia menyenaraikan nama datasource yang sebenarnya tersedia.
• template, line dan column muncul pada ralat kompil dan menunjukkan fail, baris serta lajur yang tepat.
• Stacktrace memaparkan "The Error Occurred in" dengan nombor baris dan petikan kod sumber di sekeliling baris yang gagal.
• Java Stacktrace ialah timbunan Java penuh. Di sinilah anda mencari perkataan Caused by apabila ralat dibalut oleh ralat lain.

Urutan membaca yang betul ialah dari Message untuk tahu jenisnya, kemudian template dan line untuk tahu lokasinya, kemudian Java Stacktrace untuk sampai ke punca apabila mesej itu sendiri tidak cukup jelas.

Jadual: Jenis Ralat dan Mesej Cirinya

Setiap jenis ralat meninggalkan mesej yang boleh dikenali. Mengenali bentuk mesej mempercepatkan anda terus kepada punca:

Ralat Sintaks: Baca Mesej Kompil

Ralat sintaks berlaku semasa Lucee mengkompil templat, sebelum satu baris pun dijalankan. Contoh ini meninggalkan ungkapan tidak lengkap, jumlah = 10 + ;:

<cfscript>
    // sengaja ralat: baris di bawah tidak sah, ini contoh mesej kompilasi Lucee
    jumlah = 10 + ;
    writeOutput(jumlah);
</cfscript>

Halaman ralat memulangkan jenis (template) dengan mesej sebenar berikut:

Syntax Error, Invalid Construct, at [3:19] in [ jumlah = 10 + ;]; Failed at [/var/www/uji/e500-1.cfm:3]

Perhatikan tiga maklumat yang berguna: [3:19] ialah baris 3 lajur 19, in [ jumlah = 10 + ;] mengulang ungkapan yang gagal, dan Failed at memberi laluan fail. Medan template, line dan column juga memaparkan nombor yang sama. Versi yang betul, dengan ungkapan lengkap, berjalan tanpa ralat:

<cfscript>
    jumlah = 10 + 5;
    writeOutput("Jumlah: " & jumlah);
</cfscript>

Ralat Fungsi Tidak Wujud

Memanggil fungsi yang tidak ditakrifkan ialah ralat masa jalan, jadi jenisnya ialah (expression). Contoh fungsiYangTidakWujud(1, 2) memulangkan mesej:

No matching function [FUNGSIYANGTIDAKWUJUD] found

Mesej ini sentiasa mengikut corak yang sama: nama fungsi dalam kurungan segi empat, diikuti found. Ia selalunya bermakna sama ada anda tersilap eja nama fungsi, atau anda menggunakan fungsi yang tidak wujud dalam enjin ini. Contoh sebenar yang kami temui semasa menyediakan artikel ini: sum([1, 2, 3]) memulangkan No matching function [SUM] found, kerana fungsi yang betul dalam Lucee ialah arraySum(). Ini peringatan bahawa meneka nama fungsi tanpa menyemak dokumentasi ialah punca biasa ralat jenis ini.

Null dan Kunci Struct Yang Tiada

Apabila anda membaca kunci yang tiada pada struct, Lucee melontar ralat ungkapan. Contoh ini membaca profil.emel sedangkan struct hanya ada nama dan umur:

key [EMEL] doesn't exist

Mesej ini menyebut kunci yang hilang dalam huruf besar. Ia berbeza daripada pemboleh ubah yang langsung tidak ditakrifkan, yang melontar variable [NAMA] doesn't exist. Kedua-duanya ialah petanda yang sama: anda menganggap data wujud sedangkan ia tidak. Cara selamat ialah menyemak dahulu sebelum membaca, dengan structKeyExists:

<cfscript>
    profil = { nama: "Ali", umur: 30 };
    if (structKeyExists(profil, "emel")) {
        writeOutput(profil.emel);
    } else {
        writeOutput("tiada emel");
    }
</cfscript>

Punca data hilang ini selalunya bukan pada baris yang gagal, tetapi pada cara skop dan pemboleh ubah mengalir dalam aplikasi anda. Untuk memahami mengapa pemboleh ubah itu tiada, baca panduan memahami scope CFML.

Datasource dan Rantaian Caused by

Ralat datasource memperkenalkan medan Detail dan rantaian Caused by, dua perkara paling berharga untuk dibaca. Apabila anda menanya datasource yang tidak didaftarkan, mesejnya ialah:

Datasource [tiada_ds] doesn't exist

Dan medan Detail menyenaraikan nama yang sebenarnya tersedia:

available datasource names are [app_db,mydb,luceemy,kedai,mydsn,kedaiDB,kita]

Kes yang lebih sukar ialah datasource wujud tetapi pelayan pangkalan data tidak dapat dicapai. Lucee melaporkan Connection is broken: "java.net.ConnectException: Connection refused (connect failed): 127.0.0.1:65530", dan Java Stacktrace mengandungi beberapa lapisan Caused by. Peraturan membacanya: mesej atas memberitahu apa yang gagal di permukaan, tetapi anda turun melalui setiap Caused by sehingga ke pengecualian paling dalam, iaitu di sini java.net.ConnectException: Connection refused. Punca sebenar bukanlah "connection is broken", ia ialah tiada pelayan pangkalan data mendengar pada alamat dan port itu. Untuk panduan lengkap mendiagnos ralat datasource, rujuk artikel ralat datasource not found.

Kenapa Satu Komponen Gagal Menyebabkan Semua Halaman Ralat

Satu komponen yang gagal dikompil menjatuhkan setiap halaman yang memuatkannya, bukan hanya halaman itu. Ini kerana Lucee mengkompil komponen secara berasingan sebelum halaman boleh menggunakannya. Kami menguji dengan satu komponen yang mengandungi ralat sintaks, function jumlah(a, b {, dan satu halaman yang mencipta objek daripadanya. Halaman itu sendiri betul, tetapi ia memulangkan 500 dengan mesej:

invalid argument definition, at [3:26] in [ function jumlah(a, b {]; Failed at [/var/www/uji/komponen_buruk.cfc:3]

Medan template menunjuk kepada fail .cfc, bukan fail .cfm yang anda buka. Dan Stacktrace menyebut called from /var/www/uji/e500-5.cfm: line 2, yang menunjukkan halaman itu hanya pemanggil, bukan punca. Apabila anda melihat banyak halaman gagal serentak, curigai satu komponen atau Application.cfc yang dikongsi sebelum meneliti setiap halaman satu persatu. Ralat kompil templat ini diterangkan lebih lanjut dalam artikel templat CFML yang tidak dikompil.

Menangkap Ralat dengan cftry dan cfcatch

Membiarkan ralat sampai ke halaman ralat kuning sesuai untuk pembangunan, tetapi bukan untuk pengeluaran. Balut kod berisiko dalam cftry dan cfcatch supaya anda boleh bertindak balas dengan tenang:

<cfscript>
    try {
        hasil = fungsiYangTidakWujud(1, 2);
        writeOutput(hasil);
    }
    catch (any e) {
        writeLog(text = "Ralat fungsi: " & e.message, type = "error");
        writeOutput("Ralat ditangkap: " & e.message);
    }
</cfscript>

Blok catch (any e) menangkap sebarang pengecualian ke dalam objek e. Objek itu ialah struct dengan medan yang boleh anda baca: e.type, e.message, e.detail, e.stacktrace dan e.tagContext. Kami mengesahkan kesemua medan ini wujud dalam Lucee 7.1. Dengan ralat datasource, contohnya, e.type memulangkan database dan e.detail memulangkan senarai nama datasource yang tersedia. Ini membolehkan anda mencatat maklumat yang sama yang anda baca pada halaman ralat, tetapi ke dalam log anda sendiri.

Menulis ke Log dengan writeLog dan application.log

writeLog menulis satu baris ke log bernama, dan lalai ialah log application. Apabila kod di atas dijalankan, baris berikut benar-benar muncul dalam application.log pelayan:

"ERROR","http-nio-8888-exec-6","10/17/2026","06:27:38","http://127.0.0.1:8904","uji_kod","Ralat fungsi: No matching function [FUNGSIYANGTIDAKWUJUD] found"

Setiap medan bermakna: aras, utas, tarikh, masa, URL permintaan, nama aplikasi, dan mesej anda. Log berstruktur seperti ini membolehkan anda mencari satu ralat atau satu permintaan kemudian. Untuk gambaran penuh fail log Lucee, aras log, dan putaran log, baca panduan log dan pemantauan CFML.

Bahaya Memaparkan Stack Trace kepada Pelawat

Halaman ralat Lucee penuh sangat berguna kepada pembangun dan sangat berbahaya kepada penyerang. Ia mendedahkan laluan fail pelayan, nama datasource, nama komponen, dan nombor baris kod anda. Dalam persediaan lalai, sesiapa yang membuka URL yang gagal melihat keseluruhan timbunan ini, seperti yang kami sahkan dengan curl tanpa sebarang sesi log masuk. Dua perkara perlu anda kawal sebelum melancarkan aplikasi:

• Jangan biarkan cfsetting showdebugoutput hidup. Tetapan ini menambah kotak nyahpepijat dengan nilai pemboleh ubah, masa laksana dan pertanyaan SQL pada halaman itu sendiri, dan ia kelihatan kepada semua pelawat, bukan hanya anda.
• Gantikan halaman ralat lalai dengan halaman mesra melalui onError dalam Application.cfc, supaya pelawat melihat mesej ringkas manakala butiran penuh hanya masuk ke log.

Prinsip yang sama, jangan dedahkan butiran dalaman kepada pelawat, ialah tema utama dalam panduan keselamatan web XSS dan CSRF.

Soalan Lazim (FAQ)

Apakah maksud HTTP 500 dalam Lucee?

HTTP 500 bermaksud ralat dalaman pelayan, dan dalam Lucee ia hampir selalu berpunca daripada kod CFML yang gagal semasa kompil atau masa jalan.

Apakah medan paling penting pada halaman ralat Lucee?

Message untuk jenis ralat, template dan line untuk lokasi, dan Java Stacktrace untuk menjejak rantaian Caused by hingga ke punca sebenar.

Bagaimana cara menangkap ralat supaya halaman tidak jatuh?

Balut kod berisiko dalam cftry dan cfcatch, kemudian baca medan objek cfcatch seperti e.message, e.detail dan e.stacktrace.

Bagaimana cara mencatat ralat ke fail log?

Gunakan fungsi writeLog dengan text dan type, dan baris itu akan ditulis ke application.log lalai atau log bernama yang anda tentukan.

Adakah selamat memaparkan stack trace kepada pelawat?

Tidak. Ia mendedahkan laluan fail, nama datasource dan struktur kod. Sembunyikannya dengan halaman ralat mesra melalui onError dan matikan showdebugoutput.

Sumber

• cftry, docs.lucee.org
• cfcatch, docs.lucee.org
• writeLog(), docs.lucee.org
• cflog, docs.lucee.org
• cfsetting, docs.lucee.org
• Troubleshooting Lucee Server problems, docs.lucee.org