Troubleshooting & FAQ

Quick solutions to common problems. If you can't find your answer here, contact support through CodeCanyon.

Installation Issues

Problem	Solution
Blank white page	PHP error. Check `storage/logs/laravel.log` for details. Usually wrong PHP version.
"Permission denied"	Run `chmod -R 755 storage bootstrap/cache` or set via File Manager
Database connection failed	Check database name, username, password. Make sure database exists.
500 Internal Server Error	Check error logs. Enable `APP_DEBUG=true` temporarily to see errors.
"No application encryption key"	Run `php artisan key:generate` in terminal
Install page not loading	Make sure all files uploaded. Check `.htaccess` exists.
Redirect loop	Clear browser cookies. Check `APP_URL` in `.env` matches your domain.

Problem	Solution
Can't log in	Verify email and password are correct. Use the Forgot Password link to reset your password.
Email not verified	Check your inbox (and spam folder) for the verification email. Ask an admin to verify your email manually from the admin panel.
Social login error	Check that OAuth credentials (Client ID and Secret) are correctly configured in Admin > Settings > Connections.
419 Page Expired	Refresh the page and try again. If it persists, clear your browser cookies for the site.

Email Issues

Problem	Solution
Test email not received	Check spam folder. Verify SMTP settings.
"Connection refused"	Wrong SMTP host or port. Try port 587 with TLS.
"Authentication failed"	Wrong username or password. For Gmail, use App Password.
"Connection timed out"	SMTP port may be blocked. Contact hosting provider.
Gmail not working	Enable 2FA, then create an App Password. Don't use regular password.
Emails going to spam	Set up SPF, DKIM, DMARC records for your domain.
"Stream crypto error"	Encryption mismatch. Try TLS instead of SSL or vice versa.

OAuth Issues

Problem	Solution
"Redirect URI mismatch"	Callback URL must match exactly. Check for https vs http, trailing slashes.
"Invalid client"	Client ID is wrong. Copy it again from the provider.
Button not showing	Enable the provider in Admin > Settings > Connections.
Error after clicking login	Client Secret is wrong. Regenerate and update it.
"Access denied"	User cancelled login, or app needs approval (Google).
Can't disconnect account	Users need at least one login method. Set a password first.

Common Errors

Error	Meaning	Solution
404 Not Found	Page doesn't exist	Clear route cache: `php artisan route:clear`
403 Forbidden	No permission	Check file permissions. Verify user role.
500 Server Error	Something broke	Check `storage/logs/laravel.log` for details
419 Page Expired	CSRF token invalid	Refresh page. Clear cookies.
"Class not found"	Missing files	Run `composer install`
"Vite manifest not found"	Assets not built	Run `npm install && npm run build`

Performance Issues

Problem	Solution
Slow page loads	Enable OPcache in PHP. Use a CDN for static files.
High memory usage	Increase `memory_limit` in php.ini
Database slow	Check if indexes exist. Optimize tables in phpMyAdmin.
Images loading slow	Compress images before upload. Use a CDN.

Voting & Feature Issues

Problem	Solution
Can't vote	User may have reached the vote limit for this board, or anonymous voting may be disabled. Check Admin > Settings > Voting.
Can't submit a feature	The board may require login before submitting, or feature submissions may be disabled. Check Admin > Settings > Features.
Feature not appearing after submission	The board may have moderation enabled. Check the moderation queue in Admin > Features > Pending.
Can't comment	The user's account may be inactive or banned. Check the user's status in Admin > Users.

Theme & Display Issues

Problem	Solution
Styles broken	Clear your browser cache. On a VPS, run `npm run build` to recompile assets.
Logo not showing	Re-upload the logo in Admin > Settings > General. Clear your browser cache.
Dark mode not working	Check theme settings in Admin > Theme. Note that user preference may override the default theme setting.
Layout broken on mobile	Clear your browser cache. Check for custom CSS conflicts in Admin > Theme > Custom CSS.

Cron Job Issues

Problem	Solution
Scheduled tasks not running	SSH into your server and run `php artisan schedule:run` manually to test. If it works, the issue is with your cron job configuration.
`command not found` error	Use the full path to PHP in your cron entry, e.g., `/usr/bin/php /path/to/artisan schedule:run`
Tasks run but nothing happens	Check `storage/logs/laravel.log` for errors. Verify that the scheduled tasks are registered correctly.

User Issues

Problem	Solution
Can't log in	Check email/password. Reset password if needed.
Can't vote	May have reached vote limit. Check settings.
Can't comment	User might be banned or inactive. Check status.
Not receiving emails	Check notification settings in profile. Verify email setup.

Admin Issues

Problem	Solution
Can't access admin panel	Verify you have admin role. Check in database `users` table.
Settings not saving	Check file permissions on `storage/`.
Can't delete own account	Admins can't delete themselves. Use another admin.

Update Issues

Problem	Solution
Upload fails	Increase `upload_max_filesize` and `post_max_size` in PHP
Update stuck	Click "Recover Stuck Update" button. Or delete `storage/framework/down`
Rollback not working	Restore manually from backup via FTP and phpMyAdmin
"Maintenance mode" stuck	Delete the file `storage/framework/down`

Reading Error Logs

Laravel Log

Location: storage/logs/laravel.log

Download via FTP or File Manager
Open with a text editor
Look at the most recent entries (bottom of file)

This is the primary log file for all application errors, including failed jobs, authentication issues, and database errors.

PHP Error Log

Location varies by hosting:

cPanel: Check "Error Log" in the cPanel dashboard
VPS: Usually /var/log/php_errors.log or /var/log/apache2/error.log

Enable Debug Mode (Temporarily)

Edit the .env file
Change APP_DEBUG=false to APP_DEBUG=true
Refresh the page to see detailed error messages with stack traces
Change back to APP_DEBUG=false immediately after diagnosing the issue — leaving debug mode on in production exposes sensitive information

Clearing Caches

Sometimes clearing caches fixes issues with settings not updating, routes not being found, or stale data appearing.

Via SSH (Terminal)

php artisan cache:clear
php artisan config:clear
php artisan route:clear
php artisan view:clear

Via File Manager

Delete everything inside these folders (not the folders themselves):

storage/framework/cache/data/ — delete all contents
bootstrap/cache/ — delete all contents (except .gitignore)

Resetting to Factory Settings

If all else fails:

Backup your database (export via phpMyAdmin)
Delete all files except .env
Re-upload fresh Votlie files
Run php artisan migrate:fresh (WARNING: deletes all data)
Or restore your database backup

Getting Help

If you can't solve the issue:

Check this documentation first
Search CodeCanyon comments for similar issues
Contact support with:
- What you were doing
- The exact error message
- Your PHP version
- Screenshots if possible

FAQ

Q: Can I change the domain after installation? A: Yes. Update APP_URL in .env file, then clear caches.

Q: How do I reset my admin password? A: Use the "Forgot Password" link, or update directly in the database.

Q: Can I use Votlie on multiple sites? A: Each site needs a separate license (per CodeCanyon terms).

Q: Does Votlie work with PHP 8.3? A: Yes, PHP 8.2 and 8.3 are both supported.

Q: Can I translate Votlie to another language? A: Language files are in resources/lang/. You can add translations there.

Q: How do I completely uninstall? A: Delete all files and drop the database.

Q: Is there an API? A: Basic API endpoints exist. Check routes/api.php for details.

Q: Can I customize the email templates? A: Yes, in Admin > Settings > Email > Email Templates.

Q: How often should I backup? A: Weekly at minimum. Before any update. More often for active sites.

Q: Where are uploaded files stored? A: In storage/app/public/. This folder is linked to public/storage/.

Still Need Help?

If you've tried everything here and still have issues:

Make sure you have the latest version
Check your error logs for specific messages
Contact support through CodeCanyon with detailed information

Back to Documentation Home