Common Issues

This page covers the most frequently encountered issues and how to fix them.

Blank Page or 404 After Installation

Symptom: You open your domain and see a completely blank page, a 404 error, or a directory listing of files.

Cause: Your domain is not pointing to the public/ folder.

Solution:

1. Log in to cPanel
2. Go to Domains (or Addon Domains / Subdomains depending on your setup)
3. Find your domain and check the Document Root setting
4. Change it to point to the public/ folder inside your Shop Craft directory

For example, if your Shop Craft files are in /home/username/public_html/shopcraft/, the document root should be:

/home/username/public_html/shopcraft/public

Alternative: Subdomain

If you cannot change the document root of your main domain, create a subdomain (like store.yourdomain.com) and point it to the public/ folder.

If you see a blank page but the URL is correct, also check:

• File permissions on storage/ and bootstrap/cache/
• The error log at storage/logs/laravel.log for specific error messages

---

500 Internal Server Error

Symptom: A generic "500 Internal Server Error" message appears.

Solution: Check these items in order:

1. View the Error Log

Open storage/logs/laravel.log in cPanel File Manager and scroll to the bottom. The error message will tell you exactly what went wrong.

2. Verify PHP Version

Make sure your hosting is running PHP 8.1 or higher:

1. Go to cPanel > Select PHP Version
2. Check the current version
3. If it is lower than 8.1, switch to PHP 8.1 or 8.2 and click Save

3. Check PHP Extensions

Verify all required extensions are enabled in cPanel > Select PHP Version > Extensions. See Server Requirements for the full list.

4. Check File Permissions

Ensure storage/ and bootstrap/cache/ have permission 755 or 775. See File Permissions.

5. Check .htaccess

Make sure the .htaccess file exists in the public/ folder. If it was accidentally deleted, re-extract it from the original Shop Craft ZIP file.

WARNING

If the error log shows a "Missing App Key" error, your installation may have been interrupted. Try running the installer again from scratch with a fresh extraction of the ZIP file.

---

Payment Not Working

Symptom: Customers see errors during checkout, payments are not processed, or orders are created but marked as unpaid.

Check API Keys

1. Go to Admin Panel > Settings > Payment
2. Verify that your API keys are entered correctly
3. Make sure there are no extra spaces before or after the keys

Check Live vs. Sandbox Keys

Environment	Key Type
Testing	Use sandbox/test keys
Live Store	Use live/production keys

Common Mistake

Using test/sandbox API keys on a live store is one of the most common payment issues. Sandbox keys will not process real payments. Make sure you switch to live keys before launching your store.

Check Webhook Configuration

Webhooks notify your store when payments are completed. Without them, some orders may not update their payment status correctly.

Configure these webhook URLs in your payment provider's dashboard:

Razorpay:  https://yourdomain.com/webhooks/razorpay
Stripe:    https://yourdomain.com/webhooks/stripe
PayPal:    https://yourdomain.com/webhooks/paypal

Razorpay Webhook Setup

1. Log in to your Razorpay Dashboard
2. Go to Settings > Webhooks
3. Click Add New Webhook
4. Enter the URL: https://yourdomain.com/webhooks/razorpay
5. Select the events: payment.captured, payment.failed
6. Click Create Webhook

Stripe Webhook Setup

1. Log in to your Stripe Dashboard
2. Go to Developers > Webhooks
3. Click Add endpoint
4. Enter the URL: https://yourdomain.com/webhooks/stripe
5. Select events to listen for: checkout.session.completed, payment_intent.succeeded
6. Click Add endpoint

PayPal Webhook Setup

1. Log in to PayPal Developer Dashboard
2. Go to your app under Apps & Credentials
3. Scroll to Webhooks and click Add Webhook
4. Enter the URL: https://yourdomain.com/webhooks/paypal
5. Select relevant events and save

Payment Still Failing?

• Check that your domain has a valid SSL certificate (HTTPS). Most payment providers require HTTPS.
• Verify your payment provider account is fully activated and not in a restricted state.
• Check storage/logs/laravel.log for specific payment error messages.

---

Theme Upload Fails

Symptom: Uploading a theme ZIP file shows an error or the upload appears to do nothing.

Solutions:

1. Check the ZIP File

The ZIP file must be a valid Shop Craft theme package. A valid theme ZIP contains a theme.json file that describes the theme. If you have modified or repackaged the ZIP, the structure may be invalid.

TIP

Always upload the original theme ZIP file exactly as you received it. Do not extract and re-zip it, as this can change the internal folder structure.

2. Check Storage Permissions

Theme uploads are saved to the storage/ directory. Make sure it is writable:

storage/    → permission 755 or 775

See File Permissions for instructions.

3. Check PHP Upload Limits

If the theme file is large, your hosting may reject the upload. Check these PHP settings in cPanel > Select PHP Version > Options (or PHP INI Editor):

Setting	Recommended Value
upload_max_filesize	64M or higher
post_max_size	64M or higher
max_execution_time	120 or higher

---

Plugin Upload Fails

Symptom: Uploading a plugin ZIP file shows an error.

The solutions are the same as for theme uploads — see above. The ZIP must contain a valid plugin.json file, the storage/ folder must be writable, and PHP upload limits must be high enough.

---

Email Not Sending

Symptom: Customers are not receiving order confirmations, password reset emails, or other notifications.

1. Check If Email Was Configured

If you skipped the Email Setup step during installation (Step 5), email is not configured. You need to set up SMTP credentials.

To check, look at your .env file in the root of your Shop Craft directory. If you see MAIL_MAILER=log, email is not configured for sending.

2. Configure SMTP Settings

Edit the .env file (using cPanel File Manager) and update these values:

MAIL_MAILER=smtp
MAIL_HOST=smtp.yourprovider.com
MAIL_PORT=587
MAIL_USERNAME=your-email@yourprovider.com
MAIL_PASSWORD=your-email-password
MAIL_ENCRYPTION=tls
MAIL_FROM_ADDRESS=noreply@yourdomain.com
MAIL_FROM_NAME="Your Store Name"

After Editing .env

After changing the .env file, you may need to clear the configuration cache. If your hosting provides SSH access, run php artisan config:clear. Otherwise, simply wait a few minutes for the cache to expire automatically.

3. Check SMTP Credentials

Common reasons SMTP fails:

• Wrong password (especially if using Gmail — you need an App Password)
• Wrong SMTP host or port
• Your hosting provider blocks outgoing SMTP connections (contact them to enable it)
• Your email provider requires additional authentication steps

4. Check Spam Folders

Ask customers to check their spam/junk folders. Emails from new domains are sometimes flagged by email providers until your domain builds a reputation.

Improve Email Deliverability

To reduce the chance of your store emails being marked as spam:

• Set up SPF and DKIM records for your domain (your hosting provider can help)
• Use a professional email address (like noreply@yourstore.com) instead of a free email service
• Send a test order to yourself to verify emails are arriving correctly

---

Installer Not Starting

Symptom: You visit your domain but the installer does not appear. Instead, you see the storefront or an error.

Already Installed

If you see the storefront, Shop Craft has already been installed. The installer only runs once. Your admin panel is at:

https://yourdomain.com/admin/login

Fresh Install Needed

If you need to start over with a fresh installation, you would need to:

1. Delete the storage/installed marker file
2. Drop all tables from your database (or create a new database)
3. Re-extract the Shop Craft files from the original ZIP
4. Visit your domain again to start the installer

Data Loss Warning

Starting a fresh installation will erase all your existing data — products, orders, customers, everything. Only do this if you are sure you want to start over, or if the initial installation did not complete successfully.