Troubleshooting Error Umum di Sitemas

Artikel ini mengumpulkan error yang sering terjadi saat menggunakan Sitemas beserta solusinya. Bookmark halaman ini untuk referensi cepat.

Build Errors

Error: Cannot find module ’@/…’

Penyebab: Path alias tidak terresolve dengan benar.

Solusi:

1. Pastikan tsconfig.json memiliki path alias:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@/components/*": ["src/components/*"]
    }
  }
}

2. Restart dev server setelah mengubah tsconfig.json

Error: Cannot resolve import

Penyebab: File yang diimport tidak ditemukan.

Solusi:

1. Cek case sensitivity (Linux case-sensitive)
2. Pastikan file extension benar (.astro, .ts, .tsx)
3. Cek path relatif vs absolute

# ❌ Salah (case sensitivity)
import Header from './header.astro'  # file: Header.astro

# ✅ Benar
import Header from './Header.astro'

Error: Unexpected token in MDX

Penyebab: Syntax MDX tidak valid.

Solusi:

1. Pastikan ada baris kosong sebelum dan sesudah komponen:

Teks paragraf.

<InfoBox>
Konten
</InfoBox>

Teks berikutnya.

2. Escape karakter khusus dalam JSX:

<!-- ❌ Salah -->
<div>1 < 2</div>

<!-- ✅ Benar -->
<div>1 &lt; 2</div>

Error: getStaticPaths() returned duplicate params

Penyebab: Dua artikel memiliki slug yang sama.

Solusi:

1. Cek nama folder artikel, pastikan unik
2. Jika menggunakan subfolder, pastikan helper getArticleSlug digunakan

Error: Content collection schema validation failed

Penyebab: Frontmatter tidak sesuai schema.

Solusi:

Cek frontmatter artikel sesuai dengan src/content/config.ts:

---
title: "Judul"                  # required: string
description: "Deskripsi"        # required: string
category: "Dokumentasi"         # required: enum
topic: "Sitemas"                # required: enum
tags:                           # required: array max 5
  - "Tag1"
publishedAt: 2026-01-28         # required: date
readingTime: 5                  # required: number
featured: false                 # optional: boolean
---

MDX Errors

Error: Unexpected closing tag

Penyebab: Tag tidak ditutup dengan benar atau nested backticks.

Solusi:

1. Pastikan semua tag ditutup:

<!-- ❌ Salah -->
<InfoBox>
Konten
<!-- Lupa closing tag -->

<!-- ✅ Benar -->
<InfoBox>
Konten
</InfoBox>

2. Untuk nested code blocks, gunakan 4 backticks:

````markdown
```javascript
// code
```

---

### Error: Component is not defined

**Penyebab:** Komponen tidak diimport.

**Solusi:**

Tambahkan import di awal file MDX (setelah frontmatter):

```mdx
---
title: "Judul"
---

import InfoBox from '@/components/mdx/InfoBox.astro';

<InfoBox>
Sekarang bisa digunakan
</InfoBox>
```

---

### Error: Props tidak ter-pass

**Penyebab:** Syntax props salah.

**Solusi:**

```mdx
<!-- ❌ Salah - string tanpa quotes -->
<InfoBox type=warning>

<!-- ✅ Benar - string dengan quotes -->
<InfoBox type="warning">

<!-- ✅ Benar - JavaScript expression -->
<InfoBox type={"warning"}>
```

---

## Development Server Issues

### Port Already in Use

**Error:** `Port 4321 is already in use`

**Solusi:**

<Terminal 
    title="Kill process di port 4321"
    content="lsof -ti :4321 | xargs kill -9"
/>

Atau gunakan port lain:

```bash
npm run dev -- --port 3000
```

---

### Hot Reload Tidak Bekerja

**Penyebab:** File watcher limit atau cache issues.

**Solusi:**

1. Increase file watcher limit (Linux):

```bash
echo fs.inotify.max_user_watches=524288 | sudo tee -a /etc/sysctl.conf
sudo sysctl -p
```

2. Clear cache dan restart:

<Terminal 
    title="Clear cache"
    content="rm -rf node_modules/.astro .astro dist
npm run dev"
/>

---

### Changes Not Reflected

**Solusi:**

1. Hard refresh browser: `Ctrl+Shift+R`
2. Clear browser cache
3. Restart dev server

---

## Deployment Errors

### Build Fails on Vercel/Netlify

**Penyebab umum:**

| Penyebab | Solusi |
|----------|--------|
| Node version | Set `NODE_VERSION=20` di env vars |
| Memory limit | Optimize build atau upgrade plan |
| Path case sensitivity | Linux case-sensitive, check imports |

**Debug steps:**

1. Test build lokal dulu: `npm run build`
2. Check logs di dashboard hosting
3. Compare Node version lokal vs production

---

### 404 on Dynamic Routes

**Penyebab:** `getStaticPaths()` tidak menghasilkan route tersebut.

**Solusi:**

1. Pastikan `getStaticPaths()` return semua paths
2. Check console untuk warnings saat build
3. Verifikasi `dist/` folder berisi halaman tersebut

---

### Environment Variables Not Working

**Solusi:**

1. Prefix dengan `PUBLIC_` untuk client-side access:

```bash
# Server-side only
SECRET_KEY=xxx

# Available di client
PUBLIC_SITE_URL=https://example.com
```

2. Redeploy setelah mengubah env vars

---

## Styling Issues

### CSS Not Applying

**Penyebab:** Specificity atau scope issues.

**Solusi:**

1. Astro component styles are scoped by default:

```astro
<!-- Style ini hanya berlaku di komponen ini -->
<style>
  .button { color: red; }
</style>
```

2. Untuk global styles, gunakan `is:global`:

```astro
<style is:global>
  .button { color: red; }
</style>
```

---

### Dark Mode Not Working

**Solusi:**

1. Pastikan `[data-theme="dark"]` selector ada di CSS
2. Check localStorage untuk saved preference
3. Verify toggle script berfungsi

---

## Image Issues

### Image Not Found

**Penyebab:** Path atau import salah.

**Solusi untuk images di artikel:**

```mdx
---
heroImage: ./hero.png   # Relatif ke folder artikel
---

import myImage from './screenshot.png';
```

**Solusi untuk images global:**

```astro
import logo from '@/assets/logo.png';
<!-- atau -->
<img src="/images/logo.png" alt="Logo" />
```

---

### Image Too Large / Slow

**Solusi:**

1. Gunakan Astro Image component:

```astro
import { Image } from 'astro:assets';

<Image src={myImage} alt="..." width={800} quality={80} />
```

2. Convert ke WebP format
3. Resize ke ukuran maksimal yang diperlukan

---

## Quick Debug Commands

<Accordion title="Useful debug commands">

```bash
# Clear all caches
rm -rf node_modules/.astro .astro dist

# Reinstall dependencies
rm -rf node_modules package-lock.json
npm install

# Check for TypeScript errors
npx tsc --noEmit

# Build with verbose output
npm run build -- --verbose

# Check Astro version
npx astro --version

# Validate content collections
npx astro sync
```

</Accordion>

## Masih Butuh Bantuan?

Jika masalah Anda tidak ada di daftar ini:

1. **Cek Astro Discord** — Komunitas aktif dan helpful
2. **Astro GitHub Issues** — Untuk bug reports
3. **Stack Overflow** — Tag dengan `astro` dan `mdx`

<CallToAction
  title="FAQ"
  description="Lihat pertanyaan yang sering diajukan tentang Sitemas."
  buttonText="Lihat FAQ"
  buttonLink="/blog/faq-sitemas"
  type="accent"
/>

## Kesimpulan

Sebagian besar error di Sitemas/Astro disebabkan oleh:

1. **Path/import issues** — Check case sensitivity dan path
2. **MDX syntax** — Baris kosong dan proper closing tags
3. **Schema mismatch** — Frontmatter harus sesuai config
4. **Cache** — Clear cache dan restart sering menyelesaikan masalah

Dengan memahami pola error ini, Anda bisa debug lebih cepat dan fokus ke pembuatan konten.