# Troubleshooting and FAQ

Fixes for common installation problems such as 500 errors, missing assets and stuck imports.

## 500 error

Read `storage/logs` and web/PHP logs privately. Check PHP compatibility, dependencies, database credentials, keys and writable storage/cache. After configuration changes, run `php artisan optimize` and restart services. Keep public debug mode off. Share sanitized errors only.

## Blank page or missing assets

Build the matching frontend source and deploy `public/build`. Remove a development `public/hot` file. Check document root, asset URLs and browser errors.

## Homepage works; other pages return 404

Check Nginx `try_files`, Apache rewriting or IIS URL Rewrite. The root must be `backend/public`.

## Login fails or returns 419

Check `APP_URL`, HTTPS, sessions, application key, writable session storage and cookies. Clear stale cookies after correcting the hostname. Check account status and roles if the wrong portal opens.

## Reset emails do not arrive

Send a test email from **Settings → Mail**; a failure shows the provider's reason. Then check the sender domain, spam folders, queue workers and failed jobs. The log mailer does not deliver. Confirm reset links use the reachable application hostname.

## Upload/download errors

Check storage permissions, disk settings and PHP/server limits. Private files require authorized downloads. Do not expose private storage to work around authorization errors.

## Live updates fail

Check module enablement, Reverb, WSS hostname, proxy upgrade headers and firewalls. Rebuild after `VITE_REVERB_*` changes. Shared hosting may lack persistent WebSocket support.

## Imports or exports remain pending

Check that a supervised worker consumes the `default` queue, has the current application code and can access private transfer storage. Review failed jobs and sanitized application logs. Restart workers after deployments. The configured queue `retry_after` must exceed the 60-second transfer-job timeout; see [services](https://czappstudio.com/ar/docs/installation/services#section-3).

Do not blindly retry a failed import job or re-upload its file. Review transfer history and destination records first, then use a fresh upload and validation when the cause is resolved. The hourly cleanup detects processing jobs interrupted for more than five minutes and marks them failed. If a transfer is denied after it was requested, check the requester's current permissions and whether its source module remains enabled.

## A transfer download has expired

Transfer files are available for seven days. Request a new export; if an import had not been confirmed, upload and validate it again. Completed imports do not need to be repeated when their source file expires. History metadata remains for reference. If expired files accumulate on disk, check the scheduler and `data-transfers:cleanup`.

## Installation without SSH?

Only with a secure provider equivalent for Composer, Artisan, scheduling and workers, validated on that host. Uploading files does not initialize the database.

## Can Cloudflare host the HR app?

No. Cloudflare DNS and proxy services do not provide a PHP runtime or MySQL database. This Laravel app needs a PHP server and database.

## A documented feature is missing from my menu

The manual covers optional modules and different roles. Ask the administrator to check enablement/permissions. Documentation does not grant access.