Common problems

Some common problems when authenticating, together with possible solutions. Please note that the provided problem causes are causes we observed. Of course it is possible that other reasons may cause the same problems, in that case these solutions may not work.

General errors

"That prefix doesn't live here"

If you get a response like:

{"responseCode":301,"message":"That prefix doesn't live here","handle":"<prefix>/<suffix>"} 

you are most likely contacting the incorrect instance server or using the wrong port. Please check the information that was communicated to you by SURF.

MacOS curl


* Trying x.x.x.x...
* TCP_NODELAY set * Connected to (x.x.x.x) port 8007 (#0)
* WARNING: SSL: CURLOPT_SSLKEY is ignored by Secure Transport. The private key must be in the Keychain.
* WARNING: SSL: Certificate type not set, assuming PKCS#12 format.
* SSL: Can't load the certificate "/<path>/<cert>.pem" and its private key: OSStatus -25299
* Closing connection 0
curl: (58) SSL: Can't load the certificate "/<path>/<cert>.pem" and its private key: OSStatus -25299

Possible Solution

The problem is that in older versions of MacOS curl does NOT have openssl pre-compiled. Use homebrew to download a pre-compiled curl with OpenSSL enabled:

brew install curl

Please note that this will not replace the default curl command of MacOS, you have to specifically point to the path of the newly installed version:

$ brew info curl
curl-openssl: stable 7.81. (bottled), HEAD [keg-only]
/opt/homebrew/Cellar/curl/7.81.0 (497 files, 4MB)

Using the provided path:

$ /opt/homebrew/Cellar/curl/7.81.0/bin/curl --version
curl 7.81.0 (arm-apple-darwin21.1.0) libcurl/7.81.0 (SecureTransport) OpenSSL/1.1.1m zlib/1.2.11 brotli/1.0.9 zstd/1.5.1 libidn2/2.3.2 libssh2/1.10.0 nghttp2/1.46.0 librtmp/2.3 OpenLDAP/2.6.0
Release-Date: 2022-01-05
Protocols: dict file ftp ftps gopher gophers http https imap imaps ldap ldaps mqtt pop3 pop3s rtmp rtsp scp sftp smb smbs smtp smtps telnet tftp 
Features: alt-svc AsynchDNS brotli GSS-API HSTS HTTP2 HTTPS-proxy IDN IPv6 Kerberos Largefile libz MultiSSL NTLM NTLM_WB SPNEGO SSL TLS-SRP UnixSockets zstd

Add it to your path to use the new version by default:

export PATH="/opt/homebrew/Cellar/curl/7.81.0/bin:$PATH"

HTTP 401


  • The handle server returns a JSON object that looks like this: {"responseCode":402,"handle":"myprefix/123456"}
  • Handle Server responseCode 402 (Authentication needed)
  • HTTP status code 401 (Unauthorized)

Possible solution 1

This error occurs if the username does not have admin permissions yet. Make sure it is referred to in a HS_ADMIN or HS_VLIST that has admin permissions.

Possible solution 2

This error also occurs if the username did not get permissions for this specific handle in its HS_ADMIN entry. Each user can only modify handles whose HS_ADMIN entry (or one of its HS_ADMIN entries) gives write permissions to him, either directly or by pointing to a HS_VLIST that has admin permissions and that contains the username.

SSL errors

Some problems arise from SSL library or used tools.

SSL handshake failure


SSL routines:SSL3_READ_BYTES:ssl handshake failure

Possible Solution 1

This error can occur if the private key was encrypted. Please try with an unencrypted private key.

Possible Solution 2

Make sure that openssl version 1.0.1 or higher is used. Openssl 0.98 gives handshake errors.

PEM lib


requests.exceptions.SSLError: [SSL] PEM lib (_ssl.c:2525)

Possible Solution

This error occurs if the private key was not provided, for example if a single file instead of two was provided, but the private key was not contained. For this reason, we only recommend and describe passing certificate and private key in two separate files.

Certificate verify failed


SSLError: SSL3_GET_SERVER_CERTIFICATE:certificate verify failed

Possible Solution:

This error occurs if the server certificate at the handle server can not be verified at the client side. The library default is to verify the certificate. This is normally done with a certificate from a CA authority. The credentials file can have an optional parameter HTTPS_verify to change the behaviour. The problem can be solved in several ways. By adding the correct CA certificate to the bundle on the system. By setting a path to the correct CA certificate as follows: "HTTPS_verify": "/path_to_ca_certificate/ca_certificate". Or by disabling the checking of the certificate: "HTTPS_verify": "False". The last option is the least desired option. The required CA authority file is included:


This file has a chain of three CA's (three CA certificates in the following order):

  • subject= /C=NL/O=GEANT Vereniging/CN=GEANT OV RSA CA 4
  • subject= /C=US/ST=New Jersey/L=Jersey City/O=The USERTRUST Network/CN=USERTrust RSA Certification Authority
  • subject= /C=GB/ST=Greater Manchester/L=Salford/O=Comodo CA Limited/CN=AAA Certificate Services