Skip to content
Laravel Netsons Deploy

Troubleshooting

SSH Connection

”Connection refused” or “Connection timed out”

Netsons uses port 65100 for SSH, not port 22.

Terminal window
# Wrong
ssh user@server.netsons.com


# Correct
ssh -p 65100 user@server.netsons.com

Intermittent SSH timeouts during deployment

Shared hosting servers can occasionally be slow to accept SSH connections. All SSH and SCP commands include automatic retry logic:

  • Up to 3 retries (configurable via ssh.retries in config)
  • 10-second delay between retries (configurable via ssh.retry_delay)
  • 30-second connection timeout (configurable via ssh.connect_timeout)

Only connection failures (SSH exit code 255) are retried — remote command errors are not.

To adjust retry settings, update config/netsons-deploy.php:

'ssh' => [
    // ...
    'retries' => 5,
    'retry_delay' => 15,
    'connect_timeout' => 45,
],

Then regenerate the workflow: php artisan netsons:install --force

Retries are visible in the GitHub Actions log as warning annotations.

”Host key verification failed”

Regenerate your known hosts entry:

Terminal window
ssh-keyscan -p 65100 your-server.netsons.com

Copy the full output to the SSH_KNOWN_HOSTS secret.

”Permission denied (publickey)”

  1. Verify the key is authorized in cPanel > Security > SSH Access
  2. Check SSH_PRIVATE_KEY includes the full content (from -----BEGIN to -----END)
  3. If using a passphrase, ensure SSH_KEY_PASSPHRASE is set

Git clone fails on the server

Netsons shared hosting blocks outbound SSH (port 22), so git@github.com:... URLs do not work. Use HTTPS format for GIT_REPO:

https://github.com/user/repo.git

If you were using SSH format, update the GIT_REPO variable and regenerate the workflow:

Terminal window
php artisan netsons:install --force

“fatal: could not read Username” during git clone

This means the repo is private but no token was provided. Set GIT_TOKEN — see Private Repositories.

”fatal: Authentication failed” during git clone

The GIT_TOKEN secret is set but the token is invalid or expired. For same-repo deploys, use ${{ github.token }} in the workflow. For PATs, check the token hasn’t expired and has read access to the repo contents.

”ssh: Could not resolve hostname https”

GitHub Actions escapes forward slashes in ${{ }} expression substitutions, turning HTTPS URLs into https:\/\/.... Workflows generated since v1.9.6 strip these backslashes automatically. If you see this error, regenerate the workflow with php artisan netsons:install --force.

PHP Version

Wrong PHP version or “command not found”

The default php on Netsons may point to an old version. Always use the full path:

Terminal window
/usr/local/bin/ea-php84 -v

Check available versions:

Terminal window
ssh -p 65100 user@server "ls /usr/local/bin/ea-php*"

Composer

”composer: command not found”

Use the full path with the correct PHP binary:

Terminal window
/usr/local/bin/ea-php84 /usr/local/bin/composer install

If Composer is at a different path, update composer_binary in config/netsons-deploy.php and regenerate the workflow with php artisan netsons:install --force.

”The bootstrap/cache directory must be present and writable”

This occurs during composer install on the server (git strategy) when bootstrap/cache doesn’t exist. Workflows generated since v1.9.10 create this directory automatically. If you see this error, regenerate the workflow with php artisan netsons:install --force.

”Allowed memory size exhausted”

Terminal window
/usr/local/bin/ea-php84 -d memory_limit=-1 /usr/local/bin/composer install

FTP

”Login authentication failed”

Verify FTP credentials in cPanel > Files > FTP Accounts.

Files uploaded to wrong directory

This happens when the FTP account root directory doesn’t match the expected path. For example, if FTP root is /home/user/mysite.com/ but the workflow assumes /home/user/, files end up nested incorrectly.

Fix: Set the ftp.root_path in config/netsons-deploy.php to match your FTP account root, or change the FTP account root in cPanel > Files > FTP Accounts.

See FTP Strategy — FTP Root Path for details.

Files not updating

The FTP action uses incremental sync. Check that server-dir is correct and the FTP user has write permissions.

Deployment

Migrations fail

  • Check ~/public_html/shared/.env has correct database credentials
  • Test manually:
    Terminal window
    ssh -p 65100 user@server "cd ~/public_html/current && /usr/local/bin/ea-php84 artisan migrate:status"

Storage permissions

Terminal window
ssh -p 65100 user@server "chmod -R 775 ~/public_html/shared/storage"

”.env not found” or “APP_KEY not set”

The shared .env is created from .env.example on first deploy. The workflow automatically runs key:generate on first deploy. If you need to regenerate manually:

Terminal window
ssh -p 65100 user@server "cd ~/public_html/current && /usr/local/bin/ea-php84 artisan key:generate"

.env values with special characters

Passwords or values containing &, |, \, or " are properly escaped during deployment. If you encounter issues, verify the value in ~/public_html/shared/.env on the server.

.htaccess

”500 Internal Server Error”

Check if mod_rewrite is enabled (usually enabled by default on Netsons).

If the error occurs after a fresh deploy, ensure the proxy index.php is at public/index.php (not at the deploy root). The root .htaccess rewrites all requests to public/, so the proxy must be there. If you generated your workflow before v1.6.3, run netsons:install --force to regenerate it with the fix.

Also check that the root .htaccess uses RewriteCond %{REQUEST_URI} !^/public/ to prevent a rewrite loop. Without this condition, Apache rewrites public/ to public/public/ infinitely and returns 500. Workflows generated before v1.6.4 had this issue — regenerate with netsons:install --force.

Routes return 404 (e.g., /login)

If the home page works but sub-routes return 404, the public/.htaccess (Laravel’s front controller rules) is missing from the deploy base. The deploy should copy it from the release during activation. Workflows generated before v1.6.4 did not include this step — regenerate with netsons:install --force.

Assets not loading (CSS/JS 404)

Ensure the proxy index.php and .htaccess are set up. The root .htaccess should rewrite to public/.

Release Management

”No space left on device”

Reduce kept releases:

releases-keep: '3'

Rolling back

Update the current symlink to a previous release:

Terminal window
ssh -p 65100 user@server "ln -sfn ~/public_html/releases/PREVIOUS_TIMESTAMP ~/public_html/current"

List available releases:

Terminal window
ssh -p 65100 user@server "ls ~/public_html/releases/"