Troubleshooting
Common issues and solutions for Universal PortfolioKit V2
Installation Issues
❌ Composer Install Fails
Error when running composer install
✅ Solutions
- • Check PHP version: Run
php -v(needs 8.1+) - • Update Composer: Run
composer self-update - • Clear Composer cache: Run
composer clear-cache - • Check internet connection
❌ NPM Install Fails
Error when running npm install
✅ Solutions
- • Check Node.js version: Run
node -v - • Clear NPM cache: Run
npm cache clean --force - • Delete node_modules folder and try again
- • Try
npm install --legacy-peer-deps
❌ Migration Fails
Error when running php artisan migrate
✅ Solutions
- • Check database credentials in .env file
- • Make sure database exists (create it first)
- • Verify database server is running
- • Check database user has proper permissions
Admin Panel Issues
❌ Can't Access Admin Panel
404 error when visiting /admin/login
✅ Solutions
- • Check if admin prefix was changed in settings
- • Clear route cache:
php artisan route:clear - • Make sure server is running:
php artisan serve
❌ Login Not Working
Can't log in with correct credentials
✅ Solutions
- • Check email and password are correct
- • Clear browser cache and cookies
- • Try different browser
- • Check if admin account exists in database
❌ Logged Out Automatically
Session expires too quickly
✅ Solutions
- • Check SESSION_LIFETIME in .env file
- • Clear config cache:
php artisan config:clear - • Check storage/framework/sessions folder permissions
Image Upload Issues
❌ Image Upload Fails
Error when uploading images
✅ Solutions
- • Check file size (max 2MB recommended)
- • Use supported formats: JPG, PNG, GIF
- • Check storage folder permissions:
chmod -R 775 storage - • Run storage link:
php artisan storage:link
❌ Uploaded Images Not Showing
Images uploaded but showing broken icon
✅ Solutions
- • Run:
php artisan storage:link - • Check if public/storage symlink exists
- • Verify file exists in storage/app/public
- • Clear browser cache
Frontend Display Issues
❌ Changes Not Showing
Updated content in admin but not showing on frontend
✅ Solutions
- • Hard refresh browser: Ctrl+F5 (Windows) or Cmd+Shift+R (Mac)
- • Clear view cache:
php artisan view:clear - • Clear browser cache
❌ Portfolio Filter Not Working
Category filtering doesn't work
✅ Solutions
- • Check browser console for JavaScript errors (F12)
- • Make sure projects have categories assigned
- • Clear browser cache
❌ Styling Broken
CSS not loading properly
✅ Solutions
- • Run:
npm run build - • Check if public/build folder exists
- • Clear browser cache
Database Issues
❌ Database Connection Error
Can't connect to database
✅ Solutions
- • Verify database credentials in .env file
- • Check database server is running
- • Test connection with database client (phpMyAdmin, MySQL Workbench)
- • Clear config cache:
php artisan config:clear
❌ Table Not Found Error
Error about missing tables
✅ Solutions
- • Run migrations:
php artisan migrate - • If needed, reset:
php artisan migrate:fresh - • Seed data:
php artisan db:seed
Performance Issues
❌ Slow Loading
Website loads slowly
✅ Solutions
- • Optimize images (compress before uploading)
- • Cache config:
php artisan config:cache - • Cache routes:
php artisan route:cache - • Cache views:
php artisan view:cache
Common Commands
Useful Artisan Commands
php artisan config:clear - Clear config cache
php artisan route:clear - Clear route cache
php artisan view:clear - Clear view cache
php artisan cache:clear - Clear application cache
php artisan storage:link - Create storage symlink
Browser Compatibility
Supported Browsers
- ✅ Chrome (latest)
- ✅ Firefox (latest)
- ✅ Safari (latest)
- ✅ Edge (latest)
- ✅ Mobile browsers (iOS Safari, Chrome Mobile)
📚 Still Need Help?
If you've tried everything and still have issues, review the documentation or contact support with detailed information about your problem.
Back to Documentation →