Sayudha

53 Troubleshooting Error Umum

Properties2
descriptionTiga error resmi di dokumentasi troubleshooting theme (Parameter Missing or Invalid saat add to cart, Description can't be larger than 64 kilobytes, dan masalah aset karena URL berprotokol http), plus peta error lain yang udah dibahas di buku ini dan cara ngelacaknya
tagsshopify, theme, praktik

10 menit baca

Bagian 5 buku ini soal praktik: gimana bikin theme yang gak cuma jalan, tapi bener, cepat, dan bisa dipakai semua orang. Kita mulai dari hal yang paling praktis: error yang pasti kamu temuin, dan cara nyari sebabnya.

Dokumentasi troubleshooting resmi Shopify cuma nyakup tiga error spesifik yang sering ditanyain merchant. Tiga itu kita bahas dulu secara tuntas, terus kita rangkum error lain yang udah tersebar di bab-bab sebelumnya jadi satu peta, karena waktu debugging kamu butuh nemuinnya cepat.

Error 1: Parameter Missing or Invalid

Pesannya: “Parameter Missing or Invalid: Required parameter missing or invalid”, muncul waktu pembeli nambah ke cart. Artinya form add to cart gak ngirim ID varian atau kuantitas. Ingat dari 39 Produk Variants dan High-variant Products: yang dibeli itu varian, jadi input name="id" berisi ID varian wajib ada waktu form disubmit.

Tiga penyebab umum:

  1. HTML rusak di template yang dikustomisasi (tag gak ditutup, form bersarang di form lain, input di luar <form>). Cek pakai W3C Validator. Form yang bersarang itu klasik: form produk di dalam form lain bikin browser ngabaikan salah satunya.
  2. Nyembunyiin opsi default buat produk dengan satu varian dengan ngehapus dropdown atau radio button-nya. Kalau dihapus, gak ada input id yang terkirim. Yang bener: ganti dengan hidden field yang ngirim ID varian pertama.
  3. Radio button varian tanpa yang dipilih default. Kalau pembeli gak milih dan gak ada yang checked, gak ada ID yang terkirim. Pilih yang pertama secara default.

❌ dropdown dihapus buat produk satu varian, gak ada id yang terkirim

{% form 'product', product %}
  {% unless product.has_only_default_variant %}
    <select name="id">...</select>
  {% endunless %}
  <button>Add to cart</button>
{% endform %}

✅ selalu ada input id

{% form 'product', product %}
  {% if product.has_only_default_variant %}
    <input type="hidden" name="id" value="{{ product.selected_or_first_available_variant.id }}">
  {% else %}
    <select name="id">...</select>
  {% endif %}
  <button>Add to cart</button>
{% endform %}

Pola paling aman yang dipakai theme modern: selalu satu hidden input id yang nilainya diupdate JavaScript pemilih varian, gak peduli produknya punya opsi atau gak.

Catatan: buat theme kustom, Support Shopify gak bisa bantu error ini (Design Policy). Kalau gak ketemu, rollback product.liquid (atau section produk) ke versi sebelumnya lewat riwayat file di code editor.

Error 2: Description can’t be larger than 64 kilobytes

Muncul waktu nyimpen halaman (page) yang isinya lebih dari 64KB. Ini bukan batasan Shopify, tapi batasan kolom TEXT di MySQL. Dan 64KB itu besar: 64.000 karakter, lebih dari 10.000 kata bahasa Inggris. Biasanya kejadian di halaman syarat & ketentuan, kebijakan panjang, atau halaman yang isinya HTML embed yang tebal.

Solusinya: pecah kontennya jadi bagian lebih kecil, dan bikin alternate template dari 24 Template per Halaman buat halaman itu yang ngegabungin bagian-bagiannya. Dua cara mecahnya:

  1. Banyak halaman: bikin terms-part-1, terms-part-2, dan seterusnya di admin. RTE (editor teks) admin yang bikin HTML-nya, tapi tetap cek di mode HTML biar markup-nya rapi.
  2. Banyak snippet: bikin terms-part-1.liquid dan seterusnya di /snippets. Kamu nulis HTML-nya sendiri.

Langkahnya: bikin halaman atau snippet-nya dan catat namanya, bikin template alternatif berdasarkan template page (misalnya page.terms.json yang ngerujuk section khusus), terus di template/section itu panggil bagian-bagiannya. Pakai halaman (lewat handle di object pages dari 13 Objects Global > 4. pages):

<h1>{{ page.title }}</h1>
{{ pages.terms-part-1.content }}
{{ pages.terms-part-2.content }}
{{ pages.terms-part-3.content }}

Pakai snippet:

<h1>{{ page.title }}</h1>
{% render 'terms-part-1' %}
{% render 'terms-part-2' %}
{% render 'terms-part-3' %}

Halaman utamanya (/pages/terms) cuma “wadah” dengan judul, isinya datang dari bagian-bagian. Kelebihan cara halaman: merchant tetap bisa ngedit tiap bagian di admin tanpa nyentuh kode.

Error 3: Aset Gak Muncul, Warning di Address Bar

Gejalanya: warna gak tampil benar, sebagian elemen atau gambar gak muncul, dan address bar browser nampilin peringatan (gembok dicoret, “Not secure”). Penyebabnya: sebagian aset theme (JavaScript, stylesheet, gambar, bukan link eksternal biasa) dimuat lewat http:// di toko yang jalan lewat https://. Browser modern ngeblokir mixed content (resource http di halaman https), jadi CSS atau script itu gak pernah dimuat.

Semua toko Shopify sekarang jalan lewat HTTPS, jadi ini berlaku universal. Solusinya: URL independen protokol, yang diawali // tanpa http: atau https:, biar browser ngikutin protokol halaman:

<link
  href="http://fonts.googleapis.com/css?family=Open+Sans"
  rel="stylesheet"
  type="text/css"
/>
<link
  href="//fonts.googleapis.com/css?family=Open+Sans"
  rel="stylesheet"
  type="text/css"
/>

Cara nemuinnya: cari http:// di semua file theme dan ganti dengan //. Praktisnya: download theme, pakai Replace all di editor teks, upload lagi, publikasi. Buat tau aset mana yang gagal, buka console browser, di situ tercantum resource yang diblokir. Di era sekarang, langsung pakai https:// juga sama benarnya (dan lebih disarankan dari //).

Aset yang dimuat lewat filter Shopify (asset_url, image_url, file_url, shopify_asset_url dari 19 Filters HTML, URL, Media, Color, dan Font) selalu ngasilin URL yang bener, jadi masalah ini cuma muncul di URL yang di-hardcode manual. Satu catatan lucu dari Shopify: video YouTube gak tampil di code editor online karena embed-nya pakai http, tapi di storefront tetap tampil normal.

Peta Error Lain di Buku Ini

Tiga error di atas itu yang punya halaman resmi. Tapi sepanjang buku ini udah banyak error dan sebabnya yang tersebar. Ini petanya biar gampang dicari:

1. Error Liquid di Halaman

Teks “Liquid error: …” yang muncul langsung di halaman. Penyebab umum dan babnya:

  1. Liquid error (sections/x line N): Could not find asset snippets/y.liquid: render ke snippet yang gak ada, 12 Tags Khusus Theme.
  2. Format tanggal kustom gak ada di locale bahasa aktif: date_formats harus ada di semua locale file, 33 Locales dan Translasi > 4. Tanggal dan Waktu: date_formats.
  3. translation missing: id.products.product.add_to_cart: kunci gak ada di locale file bahasa itu dan gak ada di default, 33 Locales dan Translasi. Theme Check TranslationKeyExists nangkep ini sebelum deploy.
  4. Nilai setting kosong yang dipakai tanpa cek blank, ngasilin string kosong atau nil yang dilewatin filter, 30 Settings dan Input Settings > 1. Selalu Cek Formatnya.
  5. Truthy/falsy yang salah kira (string kosong itu truthy), 09 Dasar Liquid > Truthy dan Falsy.

Cara nyarinya: pesan errornya nyebut file dan baris, buka file itu. Kalau gak ada pesan tapi hasilnya kosong, itu biasanya object nil yang di-output diam-diam.

2. Error Schema dan Upload

Muncul waktu nyimpen file di code editor atau shopify theme push:

  1. JSON schema gak valid (koma di akhir, kutip salah): section gak bisa disimpan, 26 Sections dan Section Schema.
  2. theme_info dengan theme_support_email dan theme_support_url dua-duanya, atau ada atribut yang kurang, 32 Config settings_schema.json, settings_data.json, markets.json > 1. theme_info: Metadata Theme.
  3. Setting range/number pakai string, atau range tanpa default, 30 Settings dan Input Settings > Basic Input Settings.
  4. richtext default tanpa pembungkus <p>/<ul>, liquid default string kosong atau lebih dari 50KB.
  5. tag: null di block tanpa block.shopify_attributes atau dengan lebih dari satu elemen level atas, 29 Theme Blocks Mendalam > 6. Tanpa Pembungkus: tag null.
  6. Batasan platform kelewat: 25 section per template, 50 block per section, 1.250 block per template, 8 tingkat sarang, 300 file block, 256KB per file Liquid, 1,5MB settings_data.json, 50MB paket theme. Semuanya di 21 Gambaran Arsitektur Theme > Batasan Platform.
  7. Dua template dengan nama sama (product.liquid dan product.json), 52 Online Store 2.0 dan Migrasinya > 4. Hapus Template Liquid.
  8. Dua locale default buat satu jenis file, 33 Locales dan Translasi > 1. Default Locale File.

Jalankan Theme Check (65 Theme Check Pengenalan, Konfigurasi, Commands) sebelum push, sebagian besar ini ketangkep di situ.

3. Error Ajax dan Section Rendering

Dari 51 Ajax API dan Section Rendering API dan bab terkait, dengan status HTTP-nya:

  1. 422 Cart Error waktu cart/add.js: stok kurang (sebagian tetap masuk), habis, atau semua stok udah di cart. Tampilin description-nya.
  2. 404 Cannot find variant di cart/update.js: varian gak ada atau gak dipublikasi ke Online Store.
  3. 400 no valid id or line parameter di cart/change.js: item gak ada di cart (change gak nambah), atau selling_plan dikirim pakai id bukan line.
  4. 404 Section not found di ?section_id=: ID salah, biasanya karena hardcode ID dinamis template--123__x yang berubah tiap template.
  5. null di respons ?sections= atau bundled section rendering: section gagal dirender, status tetap 200, cek tiap nilai.
  6. 417 Unsupported buyer locale di predictive search: bahasa pembeli gak didukung, cek predictiveSearch di #shopify-features dulu.
  7. 429 Throttled: request kebanyakan, hormati Retry-After, pakai debounce.
  8. Object recommendations/predictive_search/product_variant kosong: section dirender di konteks yang salah (bukan lewat endpoint API-nya), 41 Produk Recommendations, Gift Card, dan Bundles, 38 Search dan Predictive Search, 49 Delivery Pickup Availability.
  9. Request ke /cart.js ngasih harga/bahasa salah di toko multi market: URL di-hardcode tanpa window.Shopify.routes.root, 47 Markets Multi Currency, Multi Bahasa, Localization > URL Sadar Locale.

4. Masalah Form

  1. Form kontak/newsletter/login “gak jalan” atau pengunjung dilempar ke /challenge: CAPTCHA gak ke-wire, cek content_for_header, form_type, dan form dinamis, 50 Trust & Security CAPTCHA dan Security Badges > 5. Troubleshooting.
  2. Checkbox form kontak cuma ngirim satu nilai: name harus unik per checkbox, 46 Customer Sign-in, Account Component, Contact Form, Email Consent > 2. Input Opsional.
  3. Gift card recipient form lolos validasi lewat tombol accelerated checkout: form itu cuma buat Add to cart, 41 Produk Recommendations, Gift Card, dan Bundles > 2. Masukin ke Form Produk.
  4. Link akun ke /profile rusak: routes.account_url punya query parameter, pisah di ? dulu, 46 Customer Sign-in, Account Component, Contact Form, Email Consent > 5. Link ke Halaman Akun Tertentu.

5. Masalah Theme Editor

  1. Section/block gak muncul di pemilih: gak punya presets, atau block-nya _private tanpa disebut eksplisit, 26 Sections dan Section Schema, 29 Theme Blocks Mendalam > Targeting: Block Mana yang Boleh.
  2. Section muncul di template yang salah: enabled_on/disabled_on, 26 Sections dan Section Schema > 14. enabled_on.
  3. Perubahan setting gak kelihatan tanpa reload: aturan live preview theme editor, 06 Theme Editor dan Code Editor.
  4. Custom CSS merchant hilang: kamu nimpa platform_customizations di settings_data.json, 32 Config settings_schema.json, settings_data.json, markets.json > 4. Platform-controlled Settings.
  5. Setting merchant hilang setelah push: settings_data.json dan template JSON ketimpa dari lokal, pakai --nodelete/ignore atau GitHub integration, 05 Shopify CLI dan 08 GitHub Integration dan Version Control.

6. Masalah Varian dan Produk

  1. Varian ke-251 gak bisa dibeli: product.variants dibatasi 250, 39 Produk Variants dan High-variant Products > 3. Pola Kode yang Bermasalah.
  2. selected_or_first_available_variant jadi nil: kombinasi ?option_values= gak punya varian, kode harus siap nerima nil.
  3. Produk gak muncul di predictive search atau rekomendasi: seo.hidden, habis stok, harga 0, gift card, atau udah di cart, 48 SEO Metadata, hreflang, robots.txt > Nyembunyiin Halaman: seo.hidden dan 41 Produk Recommendations, Gift Card, dan Bundles > 3. Batasan.
  4. Filter gak tampil di koleksi: lebih dari 5.000 produk, atau filternya belum dibikin di Search & Discovery, 37 Filtering.

Cara Ngelacak yang Sistematis

Urutan yang biasanya paling cepat nemuin sebab:

  1. Baca pesan errornya utuh, termasuk nama file dan baris. Kebanyakan error Shopify udah nyebut lokasinya.
  2. Console dan Network tab browser: resource yang diblokir (mixed content), request Ajax yang 4xx dengan body JSON yang ngejelasin, dan error JavaScript.
  3. Theme Check di lokal buat error schema, terjemahan, dan aset.
  4. shopify theme dev dengan store yang bermasalah, biar reproduksinya pakai data asli.
  5. Preview Inspector buat masalah render dan performa di halaman tertentu, dan Theme Inspector buat profil Liquid yang lambat, 68 Theme Inspector dan Lighthouse CI.
  6. Matiin app pihak ketiga sementara, karena banyak masalah “theme” ternyata script app yang memanipulasi DOM.
  7. Bandingin sama versi sebelumnya lewat riwayat file code editor atau git, dan rollback kalau perlu.

Ringkasan

  1. Parameter Missing or Invalid: form add to cart gak ngirim id varian, karena HTML rusak, dropdown dihapus buat produk satu varian tanpa hidden input, atau radio tanpa default. Selalu ada input id.
  2. 64 kilobytes: batas kolom database buat isi halaman, pecah jadi banyak halaman atau snippet dan gabungin lewat alternate template.
  3. Aset gak muncul/warning: URL http:// di toko HTTPS diblokir, ganti ke // atau https://, cari lewat Replace all dan console browser. Filter URL Shopify selalu aman.
  4. Peta error lain: Liquid (asset missing, date_formats, translation missing, blank), schema/upload (JSON, theme_info, tipe setting, tag null, batasan platform, template dobel, locale default dobel), Ajax (422/404/400/417/429, null, konteks salah, locale), form (CAPTCHA, checkbox, gift card, account_url), theme editor (presets, enabled_on, live preview, settings_data ketimpa), produk (250 varian, nil variant, seo.hidden, filter 5.000).
  5. Lacak sistematis: pesan error, console/network, Theme Check, theme dev, inspector, matiin app, bandingin versi.

Bab selanjutnya kita bahas praktik terbaik umum bikin theme: cara pakai template, section, dan block yang bener, javascript dan stylesheet tag, version control, dan pola-pola yang bikin theme gampang dirawat.

Tampilan Grafik

Tautan Balik