Troubleshooting

This guide addresses common issues you might encounter when using Cubeta Starter and provides solutions to help you resolve them quickly.

Installation Issues

Composer Dependency Conflicts

Issue: Composer reports dependency conflicts when trying to install the package.

Solution:

1. Check your Laravel version compatibility with Cubeta Starter
2. Try using the --ignore-platform-reqs flag:

   composer require cubeta/cubeta-starter --dev --ignore-platform-reqs

3. If the issue persists, try updating your dependencies:

   composer update

Configuration File Not Published

Issue: The configuration file is not available after installation.

Solution: Manually publish the configuration file:

php artisan vendor:publish --tag=cubeta-starter-config

Generation Issues

Command Not Found

Issue: Artisan reports that the Cubeta Starter commands are not found.

Solution:

1. Make sure the package is properly installed
2. Clear the configuration cache:

   php artisan config:clear

3. Regenerate the autoload files:

   composer dump-autoload

Files Not Generated in Expected Location

Issue: Generated files are not in the expected directories.

Solution:

1. Check your configuration in config/cubeta-starter.php
2. Ensure the directories specified in the configuration exist
3. Verify you have write permissions to those directories

Relationship Generation Errors

Issue: Errors when generating models with relationships.

Solution:

1. Ensure related models exist before creating relationships
2. Check that the relationship types are correctly specified
3. For many-to-many relationships, ensure both models are created first

Usage Issues

GUI Not Accessible

Issue: Cannot access the GUI at /cubeta-starter.

Solution:

1. Ensure you're in a development environment (the GUI is only available in development)
2. Check your web server configuration
3. Verify middleware is not blocking the route

Generated Code Doesn't Work

Issue: Generated controllers, models, or other files have errors or don't work as expected.

Solution:

1. Check that you've installed all required components:

   php artisan cubeta:install api
   # or
   php artisan cubeta:install web

2. Verify that your database configuration is correct
3. Look for any custom modifications that might conflict with generated code

Translatable Fields Not Working

Issue: Translatable fields are not storing or retrieving translations correctly.

Solution:

1. Ensure you've configured available_locales in config/cubeta-starter.php
2. Check that the field is properly defined as translatable in your model
3. Verify the JSON format of your translatable data:

   {
     "en": "English value",
     "fr": "French value"
   }

Frontend Issues

Blade Components Not Found

Issue: Blade components published by the package are not found.

Solution:

1. Ensure you've installed the web components:

   php artisan cubeta:install web

2. Check that the CubetaStarterServiceProvider is registered in your bootstrap/providers.php
3. Clear the view cache:

   php artisan view:clear

Inertia.js Integration Issues

Issue: Problems with Inertia.js integration.

Solution:

1. Verify you've installed the React TS stack:

   php artisan cubeta:install react-ts
   php artisan cubeta:install react-ts-packages

2. Check that the HandleInertiaRequests middleware is registered
3. Ensure your frontend dependencies are installed:

   npm install
   npm run dev

Database Issues

Migration Errors

Issue: Errors when running migrations generated by the package.

Solution:

1. Check your database connection settings
2. Ensure the migration syntax is compatible with your database driver
3. Look for any conflicts with existing tables or columns

Seeder Errors

Issue: Errors when running seeders generated by the package.

Solution:

1. Ensure your factories are properly defined
2. Check for any missing dependencies in your models
3. Verify that related models are seeded in the correct order

Permission Issues

Role and Permission Setup Errors

Issue: Problems with the roles and permissions system (built on spatie/laravel-permission).

Solution:

1. Make sure you've installed the permissions component:

   php artisan cubeta:install permissions

2. Check that your User model uses Spatie's HasRoles trait (Spatie\Permission\Traits\HasRoles)
3. Verify that Spatie's roles, permissions, model_has_roles, model_has_permissions, and role_has_permissions tables are migrated (php artisan migrate)
4. For anything beyond installation, consult Spatie's own troubleshooting/FAQ docs

Still Having Issues?

If you're still experiencing problems after trying these solutions:

1. Check the GitHub repository for open issues
2. Review the latest changelog for any breaking changes
3. Consider opening a new issue with detailed information about your problem

Remember to include:

• Your Laravel version
• Cubeta Starter version
• Detailed description of the issue
• Steps to reproduce
• Any error messages or logs