Troubleshooting and FAQ

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.

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.