> For the complete documentation index, see [llms.txt](https://hollow-peak.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://hollow-peak.gitbook.io/docs/troubleshooting/common-problems.md).

# Common Problems

Symptoms, causes and fixes.

## The site will not load

### HTTP 500 on every page

**`APP_KEY` is not set.**

```bash
php artisan key:generate
php artisan optimize:clear
```

If that is not it, check `storage/logs/laravel-*.log`. To see the error in the browser, set `APP_DEBUG=true` **briefly** on a non-public site, then set it back.

### A blank white page

PHP is too old, or an extension is missing. Confirm PHP 8.2+ and the required extensions.

### 403 Forbidden

The document root is wrong, or permissions are. The document root must be `public/`.

### Only the home page works

`mod_rewrite` is not enabled (Apache), or the Nginx `try_files` line is missing. See **VPS Installation**.

## Database

### “The database could not be reached”

Check `DB_DATABASE`, `DB_USERNAME` and `DB_PASSWORD`. On cPanel both the database and the user are prefixed with your account name.

### “Base table or view not found”

Migrations have not run.

```bash
php artisan migrate --force
```

### Migration fails partway

Usually MyISAM. Confirm `DB_ENGINE="InnoDB ROW_FORMAT=DYNAMIC"`, drop the partially created tables, and run again.

## Images and files

### Uploaded images return 404

The storage symlink is missing.

```bash
php artisan storage:link
```

In the split `public_html` layout, create it manually — see **cPanel & Shared Hosting**.

### CSS and JavaScript missing

The document root is not `public/`. Use the Scenario 2 layout.

### Uploads rejected

Check three limits, smallest wins: the app's own setting, PHP's `upload_max_filesize` and `post_max_size`, and your host's request limit.

## Sign-in

### 419 Page Expired

The session cannot be written. Make `storage/` writable.

```bash
chmod -R 775 storage bootstrap/cache
```

### “Credentials do not match” with the right password

Wrong login page. Staff use `/staff/login`; customers use `/login`.

### Signed out immediately

`APP_URL` does not match the address you are visiting, or `SESSION_SECURE_COOKIE=true` without HTTPS.

## Changes have no effect

{% hint style="info" %}
This is almost always cached configuration.

```bash
php artisan optimize:clear
```

{% endhint %}

After editing `.env`, templates, or anything in `config/`, clear the cache.

## Email

### Nothing sends

Is `MAIL_MAILER` still `log`? That writes to the log instead of sending.

Otherwise check the SMTP host, port and encryption — 587 with `tls`, 465 with `ssl`.

### Everything goes to spam

DNS, not application configuration. Publish **SPF**, **DKIM** and **DMARC**. See **Email Setup**.

## Payments

See **Payments → Payment Troubleshooting**, which covers these in order.

## Page builder

### Dragging does nothing

Hard-reload the editor — <kbd>Ctrl</kbd>+<kbd>Shift</kbd>+<kbd>R</kbd> — to clear a cached script.

### A block shows nothing

Its module is switched off. A block belonging to a disabled feature renders nothing by design. Check **Site Management → Features**.

### A screen shows 500 after editing a template

A Blade syntax error. Run:

```bash
php artisan test --filter=ViewsCompileTest
```

It names the file and the error.

## 3D viewer

See **Portfolio → 3D Viewer & Code Showcase**.

## Getting help

Before contacting support, gather: the version, PHP and database versions, hosting type, what you did and what happened, the exact error, and the relevant lines from `storage/logs`.

{% hint style="danger" %}
**Never send credentials.** Support will never ask for your database password, API keys or administrator login.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://hollow-peak.gitbook.io/docs/troubleshooting/common-problems.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
