Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

ssh2_connect() is undefined, or returns false

ErrorFatal error: Uncaught Error: Call to undefined function ssh2_connect()

Short answer

ssh2_connect() comes from the SSH2 extension, a PECL package that is not part of PHP itself. The error means it is not installed, or it is loaded for the CLI but not for the web server's PHP. Install it for the right version, check with phpinfo(), restart PHP, and test the connection.

  • Applies to PHP 8.3, PHP 8.4, Ubuntu 24.04
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check whether this PHP has the extension at all. Run it, then compare with what the web server reports.

    php -m | grep -i ssh2
    php -r 'var_dump(function_exists("ssh2_connect"));'
  2. 2Match what you see, then jump to its fix

    1. 1function_exists prints bool(false)The SSH2 extension is not installedFix
    2. 2The CLI shows ssh2, but the browser still shows the fatal errorLoaded in the terminal, missing in the web serverFix
    3. 3ssh2_connect() returns false instead of a resourceThe extension loads but the connection failsFix

What does the error look like?

  • Fatal error: Uncaught Error: Call to undefined function ssh2_connect()
  • ssh2_connect() returns false

Cause 1 of 3

The SSH2 extension is not installed

1Check

The manual lists SSH2 as a PECL extension and says its installation follows the PECL extension chapter; Windows DLLs are on the PECL site. Nothing in a stock PHP provides it.

php --ini

2Fix

Install the extension for your PHP build. On Windows, take the php_ssh2.dll that matches your PHP version, thread safety and architecture from PECL, and add the extension line to php.ini. On Linux use your distribution's package or build the PECL package. If you cannot install extensions at all, a pure-PHP SSH library avoids the dependency.

; php.ini on Windows
extension=ssh2

3Verify

Restart PHP and run the first-step check again. It should print bool(true).

php -m | grep -i ssh2

Confirmed by php.net

Did this fix it?

Cause 2 of 3

Loaded in the terminal, missing in the web server

1Check

PHP picks its configuration file per SAPI, so the command line and PHP-FPM or Apache can read different php.ini files and scan directories. Run phpinfo() through the web server and look for an ssh2 section reading SSH2 support enabled.

<?php
echo php_sapi_name(), ' ', php_ini_loaded_file(), "\n";
var_dump(extension_loaded('ssh2'));

2Fix

Enable the extension in the php.ini or conf.d file that the web SAPI actually loads, then restart that service.

php --ini
sudo systemctl restart php8.3-fpm

3Verify

Request the test script through the web server again; extension_loaded should be true. Delete the script afterwards.

curl -s https://example.com/ssh2-check.php

Confirmed by php.net

Did this fix it?

Cause 3 of 3

The extension loads but the connection fails

1Check

The function returns a resource on success and false on error. If you pass the fourth argument or the methods array, you restrict which key exchange, host key and cipher methods are offered, and supported values depend on the libssh2 library underneath. A server that accepts none of the listed methods ends the connection.

$conn = ssh2_connect('server.example.com', 22);
var_dump($conn);

2Fix

Start with host and port only and let libssh2 negotiate. Add a methods array only for a documented reason, with entries comma separated and no spaces. After connecting, verify the host key with ssh2_fingerprint() before you authenticate.

$conn = ssh2_connect('server.example.com', 22);
if ($conn === false) {
    die('Connection failed');
}
echo ssh2_fingerprint($conn);

3Verify

The call returns a resource and the fingerprint matches the one your server shows.

ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub

Confirmed by php.net

Did this fix it?

How do I stop it coming back?

  • List ssh2 (or your SSH library) as a hard requirement in the deploy script and check function_exists at startup.
  • Verify the host key fingerprint on every connection instead of trusting the first answer.
  • Keep one php.ini change per PHP version and restart the matching service each time.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Back end

CodeIgniter 4 cannot write its cache files

CodeIgniter\Cache\Exceptions\CacheException: Cache unable to write to /var/www/app/writable/cache/

CodeIgniter 4's file cache needs a cache directory that the web server can really write to.

2 causes, each with a fix

Back end

CodeIgniter 3 loads the model but the property is undefined

The model name you are loading is the name of a resource that is already being used: user

CodeIgniter 3 expects a model file named like its class, with the first letter capitalised, for example User_model.php holding class User_model.

2 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.