Skip to content

Troubleshooting and FAQ

Jump to bottom
WhiskerEnt edited this page Aug 18, 2026 · 2 revisions

Troubleshooting & FAQ

Common Issues

500 Internal Server Error

Cause 1: Missing config file Check if config/config.php exists. If not, run the installer at /install/.

Cause 2: Wrong base_url Open config/config.php and verify base_url matches your exact domain. Common mistake: it says https://yourdomain.com/install instead of https://yourdomain.com.

Cause 3: mod_rewrite not enabled On Ubuntu/Debian:

sudo a2enmod rewrite
sudo systemctl restart apache2

On cPanel: mod_rewrite is usually enabled by default. Check with your host.

Cause 4: .htaccess not working Verify your Apache config allows .htaccess overrides. The AllowOverride directive must be set to All:

<Directory /var/www/html>
    AllowOverride All
</Directory>

Debugging: Temporarily set 'debug' => true in config/config.php to see the actual PHP error. Remember to set it back to false after fixing.

CSS Not Loading / Unstyled Pages

This is almost always a wrong base_url in config/config.php.

Test by visiting directly: https://yourdomain.com/assets/css/store.css

  • If it loads CSS code → base_url is wrong in config
  • If it shows 404 → files weren't uploaded or .htaccess is blocking static files

"Already Installed" When Trying to Reinstall

Delete storage/.installed from your server, then visit /install/.

For a completely fresh install, also:

  1. Delete config/config.php and config/database.php
  2. Drop all wk_* tables in your database (or drop and recreate the database)
  3. Visit /install/

Installer Shows "Missing Tables" Error

The schema execution may have partially failed. Go to phpMyAdmin, select your database, click SQL tab, and paste the contents of sql/schema.sql. Run it — any specific errors will show.

Common causes:

  • Database user doesn't have CREATE TABLE permission
  • Database character set issue — make sure the database uses utf8mb4_unicode_ci

Add to Cart Returns 500 Error

Check if the variant_combo_id column exists in wk_cart_items table. If not, run:

ALTER TABLE wk_cart_items ADD COLUMN variant_combo_id INT UNSIGNED DEFAULT NULL AFTER variant_id;

Images Not Showing

  1. Check storage/uploads/products/ has the image files
  2. Check the directory is readable (chmod 755)
  3. Verify images aren't blocked by .htaccess — visit https://yourdomain.com/storage/uploads/products/filename.png directly
  4. Check wk_product_images table in phpMyAdmin — make sure image_path matches actual filenames

Email Not Sending

  1. Verify SMTP settings in Admin → Settings → Email tab
  2. For Gmail: use an App Password, not your regular password
  3. Check from_email is a valid email address
  4. Test with the Test Connection button in settings
  5. Check storage/logs/ for email error logs

Login Rate Limited

After 5 failed login attempts, you're locked out for 15 minutes. Wait or clear your PHP session:

  1. Clear browser cookies for your domain
  2. Or delete session files on the server: storage/sessions/ (if using file-based sessions)

Payment Gateway Not Working

  1. Check gateway is Active in Admin → Payment Gateways
  2. Verify you're using the correct credentials (test vs live)
  3. Make sure Test Mode matches your credential type
  4. Check webhook URLs are configured correctly in the gateway dashboard
  5. For Razorpay: verify both Key ID and Key Secret are entered
  6. For Stripe: verify both Publishable Key and Secret Key

Sitemap Shows Wrong URLs

Check base_url in config/config.php. The sitemap uses this to build absolute URLs. If it shows https://yourdomain.com/install/product/..., your base_url still has /install in it.

Fix: edit config/config.php, correct the base_url, then regenerate the sitemap in Admin → SEO.

FAQ

Q: Can I use Whisker on shared hosting? Yes. Whisker is designed for shared hosting. It runs on any host with PHP 8.0+ and MySQL, including budget hosts like Hostinger, Namecheap, GoDaddy, Bluehost, etc.

Q: Does Whisker support multi-language? Not in v1.0. Multi-language support is planned for a future release.

Q: Can I use a different database like PostgreSQL? No. Whisker is built for MySQL/MariaDB only. The SQL syntax and schema use MySQL-specific features.

Q: How do I update Whisker? Download the new release, upload files (except config/config.php, config/database.php, and storage/), and run any migration SQL if provided in the release notes.

Q: Is Whisker PCI compliant? Whisker never stores credit card data. All payment processing happens on the gateway's servers (Razorpay, Stripe, etc.). Your store handles order data only.

Q: Can I remove "Powered by Whisker"? Not with the free license. Premium licenses allow branding removal.

Q: How do I back up my store?

  1. Export your database from phpMyAdmin (Export → SQL format)
  2. Download the storage/uploads/ folder (contains product images)
  3. Download config/config.php and config/database.php

Q: Maximum number of products? No software limit. Performance depends on your server. Stores with 10,000+ products run fine on decent shared hosting with proper MySQL indexing.

Q: Can I install multiple Whisker stores on one server? Yes. Each store needs its own directory (or subdomain) and its own database.

Getting Help

If your issue isn't listed here:

  1. Enable debug mode ('debug' => true in config)
  2. Check storage/logs/ for error logs
  3. Check your browser console (F12 → Console tab) for JavaScript errors
  4. Check your web server error log (cPanel → Error Log, or /var/log/apache2/error.log)

📧 mail@lohit.me — For direct support and custom development.

Whisker Cart v1.4.0 · Built by Lohit T

Clone this wiki locally