# ProInvoice — Troubleshooting Guide

**Audience:** Buyers fixing common technical problems  
**Use with:** INSTALLATION_GUIDE.md, LICENSE_GUIDE.md  

---

## How to use this guide

Each problem lists **likely cause**, **solution**, and **prevention**. Work **top to bottom** for your symptom.

> **Safety first:** Take a **backup** before changing permissions, deleting files, or running database commands.

---

## 1. Installer issues

### 1.1 Installer page does not load (404 / blank)

**Likely cause:** Web **document root** not pointing to `public`, or files uploaded to wrong folder.

**Solution:**

1. Confirm URL matches where you uploaded files.  
2. Ensure **document root** = `.../yourproject/public`.  
3. If you cannot change document root, apply the author’s **.htaccess** redirect from `public_html` to `public` (if documented).  

**Prevention:** Follow **INSTALLATION_GUIDE.md → Web root section**.

---

### 1.2 Stage 1 shows red PHP extensions

**Likely cause:** Host disabled an extension.

**Solution:**

1. Note the **missing extension name** from the installer.  
2. cPanel → **MultiPHP INI** / **Select PHP Version** → enable extension or switch PHP version.  
3. aaPanel → **PHP** → install extension package.  

**Prevention:** Use **PHP 8.2+** on a host that supports Laravel.

---

### 1.3 Stage 1 — storage not writable

**Likely cause:** Wrong **folder permissions** or wrong **owner**.

**Solution:**

1. Folders `storage` and `bootstrap/cache` must be writable by the web user.  
2. Try **755** or **775** on folders (not **777** unless host requires temporarily).  
3. On VPS, ensure **owner** is `www-data` or `www` as appropriate.  

**Prevention:** Extract ZIP preserving folders; do not run as root without fixing ownership.

---

### 1.4 Stage 2 — database connection failed

**Likely causes:** Wrong host, user not granted to DB, typo in password, wrong port.

**Solution:**

1. Re-create DB user assignment with **ALL PRIVILEGES**.  
2. Try host `127.0.0.1` instead of `localhost` (or reverse).  
3. Confirm database **name includes prefix** exactly as cPanel shows.  
4. Check for **trailing spaces** when pasting password.  

**Prevention:** Copy credentials from cPanel **MySQL Databases** screen into a secure note first.

---

### 1.5 Stage 3 — license activation failed

**Likely causes:** Wrong key, domain mismatch, API blocked, refunded purchase.

**Solution:** See **LICENSE_GUIDE.md** and section **6** below.

---

## 2. HTTP 500 Internal Server Error

**Likely causes:** `.env` misconfiguration, missing `APP_KEY`, PHP fatal error, permissions.

**Solution:**

1. Turn on **display errors** only temporarily (or read **storage/logs/laravel.log** on server).  
2. Verify `.env` exists and `APP_KEY=` is **not empty** (run `php artisan key:generate` **only** if author allows post-install CLI).  
3. Check **file permissions** on `storage` and `bootstrap/cache`.  
4. Confirm **PHP version** meets requirements.  

**Prevention:** Do not edit `.env` with rich-text editors that add hidden characters.

---

## 3. Blank white page

**Likely causes:** PHP fatal error with display off, memory limit, wrong document root.

**Solution:**

1. Check **`storage/logs/laravel.log`**.  
2. Increase **memory_limit** in PHP settings.  
3. Confirm **document root** is `public`.  

**Prevention:** Use **HTTPS** and supported PHP versions only.

---

## 3b. `.htaccess` missing on the server (404 on `/install`, Apache only)

**Symptom:** Apache reports **Not Found** for every nice URL (`/install`, `/login`); only `index.php` might work if you call it directly.

**Likely cause:** The file **`public/.htaccess`** was never uploaded. **Dotfiles** are often **hidden** in FTP clients and **dropped** by some zip tools.

**Solution:**

1. In **cPanel File Manager**, turn on **Show Hidden Files (dotfiles)**.  
2. Confirm **`public/.htaccess`** exists next to **`public/index.php`**.  
3. If it is missing, upload **`public/htaccess.dist`** from this package, then **rename** it to **`.htaccess`** (leading dot, no `.txt`).  
4. Ensure **Document Root** points to the **`public`** folder (see Installation Guide).  
5. Ensure **`AllowOverride All`** and **`mod_rewrite`** are enabled (ask host if needed).

---

## 4. CSS / JavaScript not loading (unstyled page)

**Likely causes:** **ASSET_URL** wrong, mixing HTTP/HTTPS, document root wrong, `npm` assets not built (if author expects built assets in repo).

**Solution:**

1. Open browser **Developer Tools → Network** and see which files **404**.  
2. Ensure `APP_URL` in `.env` matches your real URL (including `https://`).  
3. If the product documents `php artisan storage:link` or `npm run build`, run those **on server** if applicable.  

**Prevention:** Always access the site the same way (`https://domain.com`).

---

## 5. Database connection failed (after install)

**Likely causes:** `.env` changed, database user password rotated, host moved DB.

**Solution:**

1. Open `.env` → verify `DB_HOST`, `DB_DATABASE`, `DB_USERNAME`, `DB_PASSWORD`.  
2. Test login in **phpMyAdmin** with same credentials.  
3. Update `.env` → clear config cache if documented: `php artisan config:clear`.  

**Prevention:** Document DB credentials in a **password manager**, not sticky notes.

---

## 6. License issues (after install)

**Symptoms:** “Invalid license”, cannot save settings, red banner in admin.

**Solution:**

1. Admin → **License Status** → **Refresh**.  
2. Confirm **domain** matches license portal binding (www vs non-www).  
3. Check server **can reach internet** (outbound HTTPS).  
4. Verify **system clock** (NTP).  
5. Contact author with **purchase proof** if binding must be reset.  

**Prevention:** Activate on **final production domain**, not temporary IPs.

---

## 7. Email not sending / SMTP errors

**Symptoms:** Queued forever, “failed” in reminder logs, test email fails.

**Likely causes:** Wrong SMTP port/encryption, blocked outbound mail, bad credentials, Gmail without app password.

**Solution:**

1. Re-enter SMTP settings; test **TLS 587** or **SSL 465** consistently.  
2. Ask host if **SMTP ports** are blocked (common on cheap shared hosting).  
3. For Gmail, use **App Password** + **2FA**.  
4. If using **queue** mode, ensure **queue worker** or **cron** runs.  

**Prevention:** Use a dedicated **transactional email** provider for high volume.

---

## 8. Cron not working / reminders never send

**Symptoms:** No overdue emails, recurring invoices not generating.

**Likely causes:** Cron not added, wrong path, wrong PHP binary, `schedule:run` never executes.

**Solution:**

1. Verify cron runs **every minute** and `cd` path points to folder with `artisan`.  
2. Run manually via SSH (if you have access):  
   `php /full/path/artisan schedule:run`  
3. Check **Reminder Logs** for **pending/failed**.  
4. If using **queue**, run `queue:work` or configure **supervisor**.  

**Prevention:** Paste cron command from a **text file**, not email (avoids smart quotes).

---

## 9. Permission denied errors

**Likely causes:** Web server cannot write logs, cache, or uploads.

**Solution:**

1. Fix `storage` and `bootstrap/cache` permissions/ownership.  
2. Ensure `public` uploads path (if any) is writable.  

**Prevention:** Never deploy as root without chown to web user.

---

## 10. Wrong web root / exposed `.env`

**Symptoms:** You can download `.env` or see project folders in browser.

**Solution:**

1. **Stop** — this is a **security emergency**.  
2. Point document root to **`public`** immediately.  
3. Rotate **DB password** and **APP_KEY** per author guidance.  
4. Review **SECURITY.md**.  

**Prevention:** Never unzip so that `public_html` contains `app/` without `public` as root.

---

## 11. APP_KEY missing or invalid

**Symptoms:** Encryption errors, 500 on login.

**Solution:**

1. Author may require `php artisan key:generate` on server **once**.  
2. Never commit real `.env` to public repos.  

**Prevention:** Keep one **master .env** backup offline.

---

## 12. Storage link / file upload issues

**Symptoms:** Logos or uploads 404, “symbolic link” errors.

**Solution:**

1. If documented, run: `php artisan storage:link`  
2. On hosts blocking symlinks, use author **alternative** if provided.  

**Prevention:** Upload logos under max file size limits.

---

## 13. Slow performance

**Likely causes:** Large reports, no caching, shared host overload, debug mode on.

**Solution:**

1. Turn **APP_DEBUG=false** in production `.env`.  
2. Narrow **date ranges** in reports.  
3. Enable **OPcache** on PHP (hosting panel).  
4. Consider **VPS** if traffic is high.  

---

## 14. Addon install failed

**Likely causes:** Incompatible version, ZIP corrupt, missing dependency.

**Solution:**

1. Confirm addon matches **ProInvoice version**.  
2. Re-download addon ZIP.  
3. Check **storage/logs** during install.  
4. Contact addon author.  

---

## Still stuck?

Gather:

- Domain (and whether **www**)  
- Hosting type  
- PHP version  
- Screenshot of error  
- Relevant **laravel.log** excerpt (remove secrets)  

Open a ticket via **CodeCanyon → Support** or the author’s portal.

---

*End of Troubleshooting Guide*
