Common Issues and Troubleshooting

This guide covers common issues you may encounter when working with Laravolt v7 and provides systematic solutions.

Installation and Setup Issues

Issue: Composer Install Fails with Package Conflicts

Symptom:

Bash

composer require laravolt/laravolt
# Error: Your requirements could not be resolved to an installable set of packages.

Diagnosis:

Laravel version incompatibility (Laravolt v7 requires Laravel 10+)
PHP version mismatch (requires PHP 8.1+)
Conflicting package versions in composer.json

Solution:

Bash

# 1. Check Laravel version
php artisan --version
# Expected: Laravel Framework 10.x or 11.x
# 2. Check PHP version
php -v
# Expected: PHP 8.1.0 or higher
# 3. Update composer.json constraints
composer require laravolt/laravolt --with-all-dependencies
# 4. If still failing, check for conflicts
composer why-not laravolt/laravolt

Verification:

Bash

composer show laravolt/laravolt
# Should show version 7.x.x
php artisan vendor:publish --tag=laravolt-config
# Should publish config files successfully

Issue: Missing Service Provider After Installation

Symptom:

Bash

php artisan config:cache
# Error: Class 'Laravolt\LaravoltServiceProvider' not found

Diagnosis:

Service provider not auto-discovered
Cached config contains stale references
Package not properly installed

Solution:

Bash

# 1. Clear all caches
php artisan config:clear
php artisan cache:clear
php artisan route:clear
php artisan view:clear
# 2. Verify package installation
composer show laravolt/laravolt
# 3. Manually register provider (Laravel 10 only, if auto-discovery fails)
# Add to config/app.php:
# 'providers' => [
#     Laravolt\LaravoltServiceProvider::class,
# ]
# 4. Rebuild caches
php artisan config:cache
php artisan route:cache

Verification:

Bash

php artisan route:list | grep laravolt
# Should show Laravolt routes
php artisan config:show laravolt
# Should display Laravolt configuration

Thunderclap Generation Issues

Issue: Thunderclap Command Not Found

Symptom:

Bash

php artisan thunderclap:generate Product
# Command "thunderclap:generate" is not defined.

Diagnosis:

Thunderclap package not installed
Service provider not loaded
Command not registered

Solution:

Bash

# 1. Verify Thunderclap is installed
composer show laravolt/thunderclap
# 2. If not installed, add it
composer require laravolt/thunderclap
# 3. Publish Thunderclap config
php artisan vendor:publish --tag=thunderclap-config
# 4. Clear caches
php artisan config:clear
# 5. Verify command is available
php artisan list | grep thunderclap

Verification:

Bash

php artisan thunderclap:generate --help
# Should show command usage and options

Issue: Generated Files Have Wrong Namespace

Symptom: Generated model has namespace App\Models\Product but should be App\Domains\Product\Models\Product.

Diagnosis:

Thunderclap config not customized for domain-driven structure
Default Laravel namespace conventions applied

Solution:

Bash

# 1. Edit config/thunderclap.php
# Set custom namespace patterns:

PHP

'namespaces' => [
    'model' => 'App\\Domains\\{domain}\\Models',
    'controller' => 'App\\Domains\\{domain}\\Http\\Controllers',
    'request' => 'App\\Domains\\{domain}\\Http\\Requests',
    'resource' => 'App\\Domains\\{domain}\\Http\\Resources',
],
'paths' => [
    'model' => 'app/Domains/{domain}/Models',
    'controller' => 'app/Domains/{domain}/Http/Controllers',
    'request' => 'app/Domains/{domain}/Http/Requests',
    'resource' => 'app/Domains/{domain}/Http/Resources',
],

Bash

# 2. Regenerate with domain flag
php artisan thunderclap:generate Product --domain=Catalog
# 3. Verify generated files
ls -la app/Domains/Catalog/Models/

Verification:

Bash

# Check model namespace
head -n 5 app/Domains/Catalog/Models/Product.php
# Should show: namespace App\Domains\Catalog\Models;

Issue: Migration Already Exists Error

Symptom:

Bash

php artisan thunderclap:generate Order
# Error: Migration already exists: create_orders_table

Diagnosis:

Previous migration with same name exists
Thunderclap trying to create duplicate migration

Solution:

Bash

# Option 1: Skip migration generation
php artisan thunderclap:generate Order --skip-migration
# Option 2: Remove old migration first
rm database/migrations/*_create_orders_table.php
# Option 3: Use different table name
php artisan thunderclap:generate Order --table=customer_orders
# Option 4: Force regeneration (overwrites existing)
php artisan thunderclap:generate Order --force

Verification:

Bash

ls -la database/migrations/ | grep orders
# Should show only one migration file

Form Validation Issues

Issue: Custom Validation Rule Not Working

Symptom: Form submits successfully despite custom validation rule that should fail.

Diagnosis:

Validation rule not registered
Rule class not found
Rule logic incorrect

Solution:

Bash

# 1. Verify rule class exists
ls -la app/Rules/
# 2. Check rule is imported in Request class

PHP

use App\Rules\UniqueProductSku;
public function rules(): array
{
    return [
        'sku' => ['required', 'string', new UniqueProductSku($this->product)],
    ];
}

Bash

# 3. Test rule in isolation
php artisan tinker

PHP

$rule = new App\Rules\UniqueProductSku(null);
$rule->passes('sku', 'TEST-001');
// Should return false if SKU exists

Verification:

Bash

# Submit form with invalid data via HTTP test
php artisan test --filter=ProductValidationTest

Issue: Validation Messages Not Displaying

Symptom: Form validation fails but no error messages appear in the UI.

Diagnosis:

Blade template missing @error directives
Session flash not persisting
JavaScript intercepting form submission

Solution:

Bash

# 1. Check Blade template has error display

Blade

<input type="text" name="name" value="{{ old('name') }}">
@error('name')
    <span class="text-red-500 text-sm">{{ $message }}</span>
@enderror

Bash

# 2. Verify session driver is working
php artisan tinker

PHP

session()->put('test', 'value');
session()->get('test'); // Should return 'value'

Bash

# 3. Check for JavaScript form hijacking
# Look for event.preventDefault() in form submit handlers
# 4. Test with PrelineForm component (recommended)

Blade

<x-preline-form :action="route('products.store')">
    <x-preline-input name="name" label="Product Name" required />
    <x-preline-button type="submit">Save</x-preline-button>
</x-preline-form>

Verification:

Bash

# Submit form with invalid data and check response
curl -X POST http://localhost/products \
  -d "name=" \
  -H "X-Requested-With: XMLHttpRequest"
# Should return 422 with validation errors JSON

Asset Build Issues

Issue: Vite Build Fails with Module Not Found

Symptom:

Bash

npm run build
# Error: Could not resolve '@laravolt/preline'

Diagnosis:

NPM package not installed
Import path incorrect
Node modules cache stale

Solution:

Bash

# 1. Install Laravolt frontend assets
npm install @laravolt/preline
# 2. Clear node_modules and reinstall
rm -rf node_modules package-lock.json
npm install
# 3. Verify import path in app.js

Javascript

import '@laravolt/preline';

Bash

# 4. Rebuild assets
npm run build

Verification:

Bash

ls -la public/build/
# Should contain compiled assets
# Check browser console for errors
npm run dev
# Visit app in browser, check console

Issue: Tailwind Classes Not Applied

Symptom: Laravolt components render but have no styling.

Diagnosis:

Tailwind not scanning Laravolt views
Preline plugin not loaded
CSS not imported

Solution:

Bash

# 1. Update tailwind.config.js

Javascript

export default {
  content: [
    './resources/**/*.blade.php',
    './resources/**/*.js',
    './vendor/laravolt/**/*.blade.php', // Add this
  ],
  plugins: [
    require('@laravolt/preline/plugin'), // Add this
  ],
}

Bash

# 2. Import Preline CSS in app.css

CSS

@import '@laravolt/preline';

Bash

# 3. Rebuild assets
npm run build
# 4. Clear view cache
php artisan view:clear

Verification:

Bash

# Inspect compiled CSS
grep "preline" public/build/assets/*.css
# Should find Preline classes

Database Migration Issues

Issue: Foreign Key Constraint Fails

Symptom:

Bash

php artisan migrate
# SQLSTATE[HY000]: General error: 1215 Cannot add foreign key constraint

Diagnosis:

Referenced table doesn't exist yet
Column types don't match
Migration order incorrect

Solution:

Bash

# 1. Check migration timestamps
ls -la database/migrations/ | grep -E "(users|products|orders)"
# 2. Ensure parent table migrates first
# Rename migration file to adjust order:
mv database/migrations/2024_01_15_create_orders_table.php \
   database/migrations/2024_01_16_create_orders_table.php
# 3. Verify column types match

PHP

// Parent table (users)
$table->id(); // bigint unsigned
// Child table (orders)
$table->foreignId('user_id') // bigint unsigned - matches!
      ->constrained()
      ->cascadeOnDelete();

Bash

# 4. Reset and remigrate
php artisan migrate:fresh

Verification:

Bash

php artisan db:show
# Check foreign keys are created
mysql -e "SHOW CREATE TABLE orders\G"
# Should show FOREIGN KEY constraints

Issue: Migration Rollback Fails

Symptom:

Bash

php artisan migrate:rollback
# Error: SQLSTATE[42S02]: Base table or view not found

Diagnosis:

down() method references non-existent table
Manual database changes broke migration state
Migration batch tracking corrupted

Solution:

Bash

# 1. Check migrations table
php artisan db:table migrations
# 2. Manually fix migration state
php artisan tinker

PHP

DB::table('migrations')->where('migration', 'like', '%orders%')->delete();

Bash

# 3. Fix down() method to check table existence

PHP

public function down(): void
{
    Schema::dropIfExists('orders');
}

Bash

# 4. Reset migrations cleanly
php artisan migrate:fresh

Verification:

Bash

php artisan migrate:status
# All migrations should show "Ran"

Performance and Debugging

Issue: Slow Page Load with Suitable Tables

Symptom: Table page takes 5+ seconds to load with 1000 records.

Diagnosis:

Missing database indexes
N+1 query problem
No pagination applied

Solution:

Bash

# 1. Enable query logging

PHP

DB::enableQueryLog();
// ... render table
dd(DB::getQueryLog());

Bash

# 2. Add indexes to frequently queried columns

PHP

Schema::table('products', function (Blueprint $table) {
    $table->index('status');
    $table->index('category_id');
    $table->index(['status', 'created_at']);
});

Bash

# 3. Eager load relationships in Suitable config

PHP

public function query(): Builder
{
    return Product::query()
        ->with(['category', 'supplier']) // Eager load
        ->select('products.*');
}

Bash

# 4. Ensure pagination is enabled

PHP

public function perPage(): int
{
    return 50; // Limit results
}

Verification:

Bash

# Check query count
php artisan debugbar:clear
# Reload page, check Debugbar
# Should show < 10 queries for table render

Getting Help

If you encounter an issue not covered here:

Check logs: storage/logs/laravel.log
Enable debug mode: Set APP_DEBUG=true in .env

Run diagnostics:

Bash

php artisan about
php artisan config:show laravolt

Search documentation: Use /llms.txt index
Community support: GitHub Issues, Discord, or Laravel forums

Quick Diagnostic Commands

Bash

# System health check
php artisan about
# Clear all caches
php artisan optimize:clear
# Verify Laravolt installation
composer show laravolt/*
# Check routes
php artisan route:list | grep laravolt
# Database status
php artisan migrate:status
# View compiled config
php artisan config:show laravolt
# Test database connection
php artisan db:show