Troubleshooting Guide

This guide covers common issues and solutions when working with LamaPress.

Table of Contents

• Development Issues
• Build Issues
• Component Issues
• ACF Issues
• JavaScript Issues
• Styling Issues
• Deployment Issues

Development Issues

Vite Server Not Starting

Symptoms:

• npm run dev fails
• Port 5173 already in use

Solutions:

# Kill process on port 5173
lsof -ti:5173 | xargs kill -9

# Or change port in vite.config.js
server: {
  port: 5174,
}

Assets Not Loading in Development

Symptoms:

• Styles not applying
• JavaScript not working
• 404 errors for assets

Solutions:

1. Check Vite server is running:

   npm run dev

2. Check hot file exists:

   ls -la hot

3. Access via Herd URL, not localhost:5173:

   • ✅ http://your-site.test
   • ❌ http://localhost:5173

4. Clear browser cache:

   • Hard refresh: Cmd+Shift+R (Mac) or Ctrl+Shift+R (Windows)

Herd Site Not Loading

Symptoms:

• Site returns 404 or error
• Herd shows site as stopped

Solutions:

1. Restart site in Herd:

   • Right-click site → Restart

2. Check PHP version:

   herd php

3. Check site configuration:

   • Verify site path is correct
   • Check file permissions

Build Issues

Build Fails

Symptoms:

• npm run build exits with error
• Build process stops

Solutions:

1. Check Node.js version:

   node --version  # Should be v24.x.x

2. Clear node_modules and reinstall:

   rm -rf node_modules package-lock.json
   npm install

3. Check for syntax errors:

   • Review error messages
   • Check JavaScript/SCSS files
   • Verify imports are correct

4. Check disk space:

   df -h

Assets Missing After Build

Symptoms:

• dist/ directory empty or incomplete
• Manifest file missing

Solutions:

1. Verify build completed:

   npm run build
   # Check for errors

2. Check dist/ directory:

   ls -la dist/

3. Check file permissions:

   chmod -R 755 dist/

4. Rebuild:

   rm -rf dist/
   npm run build

Component Issues

Component Not Rendering

Symptoms:

• Component doesn't appear on page
• PHP errors in logs

Solutions:

1. Check component file exists:

   ls components/blocks/your-component/index.php

2. Check function call:

   // ✅ Correct
   llBlock('your-component', ['fields' => $fields]);
   
   // ❌ Wrong
   llBlock('your_component', ['fields' => $fields]);

3. Check for PHP errors:

   • Enable WP_DEBUG in wp-config.php
   • Check error logs

4. Verify data is passed:

   var_dump($fields); // Debug output

Component JavaScript Not Loading

Symptoms:

• Component renders but JavaScript doesn't work
• No errors in console

Solutions:

1. Check data-component attribute:

   <div data-component="blocks/your-component">

2. Verify JavaScript file exists:

   ls components/blocks/your-component/index.js

3. Check default export:

   // ✅ Correct
   export default class YourComponent {
     // ...
   }

4. Check browser console:

   • Look for import errors
   • Check for JavaScript errors

Component Not Initializing

Symptoms:

• Component exists but init() not called
• No console logs from component

Solutions:

1. Check element exists when component loads:

   constructor(element) {
     if (!element) {
       console.error('Element not found');
       return;
     }
     this.element = element
     this.init()
   }

2. Check for JavaScript errors:

   • Browser console
   • Network tab for failed imports

3. Verify component is in DOM:

   console.log('Element:', this.element);

ACF Issues

Fields Not Showing

Symptoms:

• ACF fields don't appear in admin
• Field groups missing

Solutions:

1. Check ACF Pro is installed:

   • Verify plugin is active
   • Check license is valid

2. Check field group key is unique:

   $key = 'unique_key_here'; // Must be unique

3. Clear ACF cache:

   • Deactivate and reactivate ACF
   • Or clear WordPress cache

4. Check template is correct:

   llSection('section_name', 'unique_key');

Field Values Not Saving

Symptoms:

• Fields appear but values don't save
• Data lost on save

Solutions:

1. Check field keys:

   'key' => $name . '_01', // Must be unique

2. Check user permissions:

   • User must have edit permissions
   • Check user role capabilities

3. Check for JavaScript errors:

   • Browser console
   • May prevent form submission

4. Check database:

   • Verify WordPress can write to database
   • Check table permissions

Flexible Content Not Working

Symptoms:

• Flexible section doesn't show sections
• Sections not available

Solutions:

1. Check section acf.php files exist:

   ls components/sections/*/acf.php

2. Verify section definitions:

   // In section acf.php
   $key = 'section_name';
   $name = 'section_name';
   $title = 'Section Title';

3. Check template call:

   llSection('flexible', 'flexible_key');

JavaScript Issues

Module Not Found

Symptoms:

• Console error: "Failed to fetch dynamically imported module"
• Component doesn't load

Solutions:

1. Check file path:

   // ✅ Correct
   data-component="blocks/accordion"
   
   // ❌ Wrong
   data-component="blocks/accordion/index"

2. Verify file exists:

   ls components/blocks/accordion/index.js

3. Check default export:

   export default class Accordion {
     // ...
   }

4. Clear browser cache:

   • Hard refresh
   • Clear cache and reload

GSAP Animation Not Working

Symptoms:

• Animations don't play
• Timeline errors

Solutions:

1. Check GSAP is imported:

   import { gsap } from 'gsap/all'

2. Check ScrollTrigger is registered:

   import { ScrollTrigger } from 'gsap/ScrollTrigger'
   gsap.registerPlugin(ScrollTrigger)

3. Verify element exists:

   if (!this.element) {
     console.error('Element not found');
     return;
   }

4. Check timeline cleanup:

   destroy = () => {
     killTimeline(this.timeline);
   }

Styling Issues

Styles Not Applying

Symptoms:

• Tailwind classes not working
• Custom styles missing

Solutions:

1. Check build completed:

   npm run build

2. Verify CSS is loading:

   • Check Network tab
   • Verify CSS file exists in dist/

3. Check class names:

   <!-- ✅ Correct -->
   <div class="ll-container">
   
   <!-- ❌ Wrong -->
   <div class="container">

4. Clear browser cache:

   • Hard refresh
   • Clear cache

Tailwind Classes Not Generated

Symptoms:

• Custom Tailwind classes don't work
• Classes not in compiled CSS

Solutions:

1. Check Tailwind config:

   content: [
     './components/**/*.php',
     './src/**/*.js',
   ]

2. Rebuild:

   npm run build

3. Check safelist:

   safelist: [
     'll-theme-dark',
     'll-heading-2xl',
   ]

Deployment Issues

Assets Not Loading on Staging/Production

Symptoms:

• Styles missing
• JavaScript not working
• 404 errors

Solutions:

1. Verify build completed:

   npm run build

2. Check dist/ is committed:

   git status
   git add dist/
   git commit -m "Build assets"

3. Verify file permissions:

   chmod -R 755 dist/

4. Check manifest file:

   ls dist/.vite/manifest.json

Build Fails on Server

Symptoms:

• Deployment fails
• Build errors

Solutions:

1. Check Node.js version:

   node --version  # Should match local version

2. Check npm version:

   npm --version

3. Use npm ci instead of npm install:

   npm ci  # Clean install from package-lock.json

4. Check server resources:

   • Disk space
   • Memory limits
   • Timeout settings

Getting Help

If issues persist:

1. Check error logs:

   • WordPress debug log
   • Server error logs
   • Browser console

2. Review documentation:

   • Relevant guide sections
   • Code examples
   • Best practices

3. Ask the team:

   • Share error messages
   • Include relevant code
   • Describe steps to reproduce

Related Documentation

• Development Environment - Setup issues
• Build Process - Build issues
• Component System - Component issues
• JavaScript Architecture - JS issues

---

Next Steps:

• Review relevant documentation sections
• Check error logs for specific errors
• Ask the team if issues persist