Troubleshooting##

Panduan troubleshooting untuk masalah umum di Lokio CLI.

Common Issues##

1. "lokio.yaml not found"##

Error:

lokio.yaml not found. Run 'lokio init' first.

Solution:

lokio init

Cause:

• Project belum di-initialize
• Berada di directory yang salah

2. "configs.yaml not found"##

Error:

configs.yaml not found. Run 'lokio init' first.

Solution:

lokio init

Cause:

• File lokio/configs.yaml tidak ada
• Folder lokio/ tidak ada

3. "Template file not found"##

Error:

Template file not found: example.lokio

Solution:

1. Check file ada di lokio/templates/example.lokio
2. Check path di configs.yaml benar:

   path: "example.lokio"  # Relatif ke lokio/templates/

3. Check file name match dengan path di config

Common Mistakes:

• Path include templates/ prefix → seharusnya hanya nama file
• File name typo
• File di folder yang salah

4. "Invalid configs.yaml format"##

Error:

Invalid configs.yaml format.

Solution:

1. Check YAML syntax
2. Check required fields ada:
   • name
   • description
   • path
   • output
   • parameters (array)
3. Validate YAML dengan online validator

Common Mistakes:

• Missing required fields
• Wrong indentation
• Invalid YAML syntax
• Missing quotes untuk strings dengan special chars

5. "Template name already exists"##

Error:

Template name already exists

Solution:

• Gunakan nama template yang berbeda
• Atau hapus template lama dulu:

  lokio template remove <old-name>

6. Parameter tidak muncul saat generate##

Symptoms:

• Parameter yang ditambah di configs.yaml tidak muncul sebagai prompt

Solution:

1. Check parameter ada di configs.yaml:

   parameters:
     - name: "myParam"
       type: "string"
       required: true
       prompt: "My parameter"

2. Check YAML syntax benar
3. Check parameter format benar (name, type, required, prompt)
4. Restart generate command

Common Mistakes:

• Parameter tidak di array parameters:
• Missing required fields
• Wrong indentation

7. Case transformation tidak bekerja##

Symptoms:

• <%= Name %> tidak menjadi Capitalize
• Helper functions tidak bekerja

Solution:

1. Check variable name: <%= Name %> (huruf besar pertama)
2. Check helper function: <%= capitalize(name) %>
3. Check input adalah string (bukan number/boolean)

Common Mistakes:

• Variable name typo
• Helper function typo
• Input bukan string

8. Output path tidak benar##

Symptoms:

• File di-generate ke path yang salah
• Path tidak menggunakan parameters

Solution:

1. Check output path di configs.yaml:

   output: "src/components/<%= name %>.tsx"

2. Check EJS syntax benar
3. Check parameters ada dan benar

Common Mistakes:

• EJS syntax salah: {{ name }} → seharusnya <%= name %>
• Parameter name typo
• Path tidak menggunakan EJS

9. File sudah ada, tidak ditanya overwrite##

Symptoms:

• File di-generate tanpa konfirmasi overwrite

Solution:

• Ini seharusnya tidak terjadi, file yang sudah ada harus ditanya
• Check apakah file benar-benar ada
• Check permissions

10. Template tidak muncul di list##

Symptoms:

• Template yang ditambah tidak muncul di lokio list

Solution:

1. Check template ada di configs.yaml
2. Check YAML syntax benar
3. Check template name unique
4. Run lokio list untuk lihat error

Common Mistakes:

• Template tidak di array templates:
• YAML syntax error
• Missing required fields

YAML Syntax Issues##

Wrong Indentation##

Wrong:

templates:
- name: "example"  # Missing indentation

Correct:

templates:
  - name: "example"  # Correct indentation

Missing Quotes##

Wrong:

name: example component  # Space needs quotes

Correct:

name: "example component"

Array Syntax##

Wrong:

parameters: name, type  # Not array

Correct:

parameters:
  - name: "name"
    type: "string"

EJS Syntax Issues##

Wrong EJS Tags##

Wrong:

{{ name }}        # Handlebars syntax
${name}           # Template literal

Correct:

<%= name %>       # EJS output
<% code %>        # EJS code

Unclosed Tags##

Wrong:

<% if (condition) { %>
  // Missing closing tag

Correct:

<% if (condition) { %>
  // Content
<% } %>

File Path Issues##

Absolute vs Relative##

Wrong:

path: "/templates/example.lokio"      # Absolute
path: "templates/example.lokio"      # Wrong prefix

Correct:

path: "example.lokio"                 # Relative to lokio/templates/
path: "components/example.lokio"     # With subfolder

Output Path##

Wrong:

output: "components/<%= name %>.tsx"  # No src/ prefix

Correct:

output: "src/components/<%= name %>.tsx"

Debugging Tips##

1. Check Files##

# Check lokio.yaml exists
cat lokio.yaml
 
# Check configs.yaml
cat lokio/configs.yaml
 
# Check template file
cat lokio/templates/example.lokio

2. Validate YAML##

# Online validator
# https://www.yamllint.com/
 
# Or use yq (if installed)
yq eval lokio/configs.yaml

3. Test Template##

# Generate dengan verbose
lokio generate
 
# Check output
ls -la src/components/

4. Check Parameters##

# List templates dengan detail
lokio list
 
# Check parameters di configs.yaml
cat lokio/configs.yaml | grep -A 10 parameters

Getting Help##

Jika masih ada masalah:

1. Check Documentation

   • Getting Started
   • Commands
   • Template Management

2. Check Examples

   • Examples

3. Validate Config

   • Check YAML syntax
   • Check required fields
   • Check file paths

4. Test Simple Case

   • Start dengan template sederhana
   • Test dengan 1 parameter
   • Gradually add complexity

Error Messages Reference##

Prevention##

Untuk menghindari masalah:

1. ✅ Always validate - Check YAML syntax sebelum save
2. ✅ Use examples - Start dari contoh yang bekerja
3. ✅ Test incrementally - Tambah complexity gradually
4. ✅ Check paths - Pastikan file paths benar
5. ✅ Use descriptive names - Avoid typos dengan clear names