Troubleshooting

SSH Connection

”Connection refused” or “Connection timed out”

Netsons uses port 65100 for SSH, not port 22.

# Wrong
ssh user@server.netsons.com

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

”Host key verification failed”

Regenerate your known hosts entry:

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

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:

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

Check available versions:

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:

/usr/local/bin/ea-php84 /opt/cpanel/composer/bin/composer install

“Allowed memory size exhausted”

/usr/local/bin/ea-php84 -d memory_limit=-1 /opt/cpanel/composer/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:

  ssh -p 65100 user@server "cd ~/public_html/current && /usr/local/bin/ea-php84 artisan migrate:status"

Storage permissions

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:

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).

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:

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

List available releases:

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