Common ProjectSend Install Errors

Most errors after a ProjectSend zip install fall into four categories: an Apache or nginx misconfiguration, a database compatibility flag, a user mismatch between your web server and PHP-FPM, or a missing reverse proxy header. Start by reading storage/logs/laravel.log -- it names the specific error and usually points to the fix.

This note is based on ProjectSend 2.8.1 (November 2026).

Apache: 500 on a fresh install

If every request returns a 500 error and your server is Apache, the most likely cause is that AllowOverride is not set to All for your document root. Without it, Apache ignores the .htaccess file that ships with ProjectSend and URL rewriting stops working. This was first reported as issue #1778 and documented in the Install from the zip guide as of 2.5.0.

Add AllowOverride All to the <Directory> block covering your document root:

<Directory /var/www/projectsend/public>
    AllowOverride All
    Options -Indexes
</Directory>

Then enable mod_rewrite if it is not already on, and reload Apache:

a2enmod rewrite
systemctl reload apache2

If the app runs in a subdirectory rather than at the root of your domain, also set RewriteBase in public/.htaccess to match the subdirectory path.

MariaDB and MySQL compatibility

Fresh installs fail during migration on MariaDB before 10.10 and on MySQL 5.7 when explicit_defaults_for_timestamp is set to OFF. The installation wizard completes the web steps but the database migration stops mid-way. The error in storage/logs/laravel.log references the failing migration class and names the flag. This was fixed in ProjectSend 2.7.1 (issue #1816), which added explicit SQL to bring the flag into a known state before the migration runs. Upgrade to 2.7.1 or later.

If you need to stay on an older database version, enable the flag in your database config (my.cnf on Linux, my.ini on Windows) under [mysqld] and restart the database service:

[mysqld]
explicit_defaults_for_timestamp=ON

nginx and PHP-FPM: downloads return 0 bytes

When nginx and PHP-FPM run as different system users -- the default on many distributions -- ProjectSend uploads succeed but file downloads return a 0-byte response or a 404. PHP-FPM writes files that the web server user cannot read.

Add FILES_WEB_SERVER_READABLE=true to your .env file. This tells the app to set group-readable permissions when files are written, so the web server can read them. For files already on disk, fix permissions once with:

chmod -R o+r storage/app/files

For new installs, also set the umask in your PHP-FPM pool configuration so that all uploaded files are group-readable. Open your pool config (usually /etc/php/<version>/fpm/pool.d/www.conf) and add:

[www]
php_value[umask] = 0022

Restart PHP-FPM after the change. The full steps, including the storage/app/public symlink needed for public file serving, are in the Install from the zip guide under the PHP-FPM user section.

Other common errors

A few other errors come up regularly on new installs:

• 419 after every form submission: you are behind a reverse proxy. Set TRUSTED_PROXIES in .env to the IP or CIDR of your proxy. See the reverse proxy guide for the exact syntax -- the same variable works for zip installs.
• Blank page on the first request: PHP is probably hitting a fatal error before the response starts. Check storage/logs/laravel.log and confirm all required extensions are installed (mbstring, pdo_mysql, fileinfo, gd, curl).
• Storage permissions: the storage/ directory tree must be writable by PHP-FPM. Run chmod -R 775 storage/ and chown -R <fpm-user>:<web-group> storage/ substituting your PHP-FPM user and web server group.
• .env changes have no effect: run php artisan optimize:clear and restart PHP-FPM. Laravel caches the config; changes to .env are not picked up until the cache is cleared.

More notes on getting ProjectSend running are in the Installation category.

If you run into an error not covered here, search the GitHub issue tracker first -- many zip install problems have already been diagnosed there. For questions, the Discord server is the fastest way to reach the community. The docs live in the app repository and PRs to improve them are welcome.