Error running setup:upgrade on live server in magento 2.2.4 I get Port must be configured within host parameter (like localhost:3306

Error running setup:upgrade on live server in magento 2.2.4 I get Port must be configured within host parameter (like localhost:3306

August 22, 2026 · Illustrated author avatarBy Stefan Bogdanescu
Error running setup:upgrade on live server in magento 2.2.4 I get Port must be configured within host parameter (like localhost:3306

Resolving Magento 2 Database Connection Errors

When working on a live Magento server, you may encounter database connection errors when running commands like setup:upgrade. In many cases, these issues stem from incorrect configuration of the database details in your env.php or app/etc/env.php files.

Understanding the Error Message

The error message “Port must be configured within host parameter (like localhost:3306)” suggests that Magento is unable to establish a connection with your database because it cannot recognize the port number. The subsequent errors indicate that the database server refused the connection attempt.

[Zend_Db_Adapter_Exception]
SQLSTATE[HY000] [2002] Connection refused

[PDOException]
SQLSTATE[HY000] [2002] Connection refused

Step-by-Step Solution

To resolve this issue, you need to ensure your database connection parameters are correctly set in the app/etc/env.php file.

  1. Locate and open the env.php or app/etc/env.php file using a text editor or an SSH terminal.

  2. Look for the db_host configuration parameter under the db_connection_default array:

'default' => [
    'connection' => [
        'adapter' => 'mysql',
        'host' => 'localhost',  // Change this line
        'name' => 'magento_database_name',
        'user' => 'magento_user',
        'password' => 'magento_password'
    ],
],
  1. The host parameter should be set to the correct hostname or IP address of your database server. If you’re using a local MySQL installation, it might look like localhost:3306.

  2. If your domain name resolves to your server’s IP address, you can also use that as the host value.

  3. Save the changes and close the file.

Best Practices

  • Always double-check the database details in the env.php file after any server migration or configuration changes.
  • Ensure that the MySQL service is running on your server.
  • If you’re using a remote database, verify that the firewall rules allow connections from your Magento server to the database.

Debugging Tips

If the issue persists even after updating the env.php file:

  1. Enable Magento’s debug mode in the app/etc/env.php file:
'db' => [
    'transaction_model_class' => 'Magento\Framework\DB\Transaction',
    'log' => false,
    'logger' => null,
],
  1. Run your command again: php bin/magento setup:upgrade

  2. Check the Magento exception logs located in var/log/exception.log for more detailed information about the error.

Conclusion

Resolving database connection errors in Magento typically involves verifying and updating the database configuration parameters in the env.php file. Always ensure that the host value matches your actual MySQL server’s address or hostname, including the correct port number if needed.

Remember to keep your server’s firewall settings open for communication between your Magento application and the database server. If you’re still experiencing issues after following these steps, consider reaching out to a Magento developer or support team for further assistance.

For more advanced troubleshooting techniques and best practices in Magento 2 development, visit Laravel Company.

Magento 2 Database Configuration Deployment

Our network