Troubleshooting Python with Posit Connect

General errors when using system version of Python

Error:

General Python errors when deployed Python content to Posit Connect (i.e., apps or documents that use the reticulate package or Jupyter Notebooks).

Most of the issues encountered with Python and Posit Connect occur when trying to use the version of Python that is included with the system (typically located at /usr/bin/python).

Solution:

Ensure that you are using a version of Python that was installed from source (typically located in /opt/Python/X.Y.Z) as recommended in the Posit Connect admin guide (followed by installing pip and virtualenv) instead of the version of Python included with the system.

Installing Python from source will result in a standalone Python environment that is separate from the system/framework installation of Python that won't be affected when you update system packages.

This also allows you to install and use multiple versions of Python with Posit Connect that can be used by different published content/apps.

Mismatched / expected version errors when using Python installed from source

Error:

The following error can occur with RStudio Connect 1.7.0 when using a Python installation from source (typically in /opt/Python/X.Y.Z/) when a similar version of Python exists on the system (typically at /usr/bin/python).

The Python installation in the environment was expected to have
version 3.6.8 but is reporting version 3.6.7 ; the Python
installation for version 3.6.8 may have changed. RStudio Connect
needs to be restarted. Please contact the server administrator.

In the above example, this error was generated when deploying Python content to RStudio Connect on Ubuntu 18.04 with a system version of Python 3.6.7 and a version of Python 3.6.8 installed from source.

This error occurs due to an issue with virtualenv behavior and how Python is configured to use shared libraries at runtime.

Solution:

Compile Python from source with the additional --disable-new-dtags flag during the configure step in the RStudio Connect documentation steps to Build Python from Source.

The corrected configure command to use is as follows:

./configure \
 --prefix=/opt/Python/${VERSION} \
 --enable-shared \
 --enable-ipv6 \
 LDFLAGS=-Wl,-rpath=/opt/Python/${VERSION}/lib,--disable-new-dtags

SSL and verification errors when using the Jupyter Notebook extension with Posit Connect

Error:

The following SSL or verification errors can occur when using the Jupyter Notebooks extension (rsconnect_jupyter) to connect to RStudio Connect or publish a Jupyter Notebook:

Failed to verify Posit Connect is running at https://<server-address>.
Please ensure the server address is valid.

A TLS error has occurred when trying to reach the Posit Connect server.
* Ensure that the server address you entered is correct.
* Ensure that your Jupyter server has proper certificates.

Solution:

This issue is either caused by a self-signed SSL CA certificate that is not recognized by the client machine running Jupyter Notebooks, an incomplete SSL certificate chain, or by Python not configured to use the correct/system-wide SSL certificates. This is a limitation of how Python handles CA certificates that can occur depending on how Python was installed.

1. Ensure that you have the latest version of the certifi and related packages installed by running the following command in a terminal:

pip install -U certifi

# or, if you are using conda
conda install certifi ca-certificates openssl

2. If you installed Python from python.org and are using macOS, be sure that you ran the Install Certificates script located in the Python installation directory. On macOS, this script is located at /Applications/Python 3.x/Install Certificates.command. This script will install the certifi package and configure Python to point to a current curated set of root CA certificates.

3. Verify that your instance of Posit Connect or load balancer is sending a full, valid CA certificate chain using a tool such as https://www.ssllabs.com/ssltest/. You can verify this in your Posit Connect configuration file (default: /etc/rstudio-connect/rstudio-connect.gcfg) by ensuring that the file referenced in the HTTPS.Certificate option includes the site certificate and any necessary intermediate CA certificates within the same file.

4. To modify where Python is searching for CA certificates, you can manually set the path to the CA certificate in the SSL_CERT_FILE or SSL_CERT_DIR environment variables, which should be set in the command that runs Jupyter Notebooks. To accomplish this, you can start Jupyter Notebooks using a command such as:

SSL_CERT_FILE=/path/to/ssl/certificate/file jupyter notebook

Note that you should set the SSL_CERT_FILE or SSL_CERT_DIR in the command that runs Jupyter Notebooks as opposed to within the notebook process after Jupyter Notebook has started. The SSL certificate file should include the site certificate and any necessary intermediate CA certificates within the same file.

For more information about using SSL certificates within Python environments, refer to the following article on Certificate verification in Python standard library HTTP clients.

NameError when deploying Python content to Posit Connect

Error:

You may encounter the following error when deploying Python content to Posit Connect:

2019/01/25 22:57:41.173653408 label: setup
2019/01/25 22:57:44.527159916 Quitting from lines 12-16 (demo-notebook.Rmd)
2019/01/25 22:57:44.527336538 Error in py_initialize(config$python, config$libpython, config$pythonhome, :
2019/01/25 22:57:44.527339368 NameError: name 'prev' is not defined
2019/01/25 22:57:44.527357490
2019/01/25 22:57:44.527358374 Detailed traceback:
2019/01/25 22:57:44.527368749 File "<string>", line 46, in <module>
2019/01/25 22:57:44.527369751 File "<string>", line 46, in <listcomp>
2019/01/25 22:57:44.527377233 Calls: local ... ensure_python_initialized -> initialize_python -> py_initialize -> .Call
2019/01/25 22:57:44.527436361 In addition: Warning message:
2019/01/25 22:57:44.527549465 In res[i] = withCallingHandlers(if (tangle) process_tangle(group) else process_group(group), :
2019/01/25 22:57:44.527589661 number of items to replace is not a multiple of replacement length
2019/01/25 22:57:44.528223479
2019/01/25 22:57:44.528973397 Execution halted
Task: uj2MsY07KM2RSc9L Rendering exited abnormally: exit status 1 

Solution:

A workaround is to downgrade to virtualenv 16.1.0 and remove the associated Python environments in /var/lib/rstudio-connect/python-environments by running the following commands:

sudo /opt/Python/X.Y.Z/bin/pip install virtualenv==16.1.0
rm -rf /var/lib/rstudio-connect/python-environments/

where X.Y.Z is the version of Python you are using.

Error with reticulate when deploying Python content to Posit Connect

Error:

* reticulate is in use, but python was not specified
Execution halted

Solution:

This error indicates that your app or document uses Python via the reticulate package, but your RStudio IDE is not configured to point to a Python environment to use for local testing and publishing.

Instead of using the reticulate::use_* group of functions, we recommend using the RETICULATE_PYTHON environment variable on your local machine to publish apps and documents with Python content to Posit Connect using the push-button publishing functionality of the Posit IDE.

Refer to the support article on Using Python with Posit Connect for more information on how to configure this environment variable.

SSL errors when using Python installed from source

Error:

The following errors can occur after installing Python from source, such as when installing pip into the Python environment.

pip is configured with locations that require TLS/SSL,
however the ssl module in Python is not available.

Retrying (Retry(total=1, connect=None, read=None, redirect=None,
status=None)) after connection broken by 'SSLError("Can't connect
to HTTPS URL because the SSL module is not available.")':
/simple/pip

And the following error occurs when you attempt to import the ssl library in the version of Python that was installed from source:

$ /opt/Python/3.7.1/bin/python
Python 3.7.1 (default, Nov 29 2018, 16:28:02)
[GCC 4.8.4] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import ssl
Traceback (most recent call last): 
File "<stdin>", line 1, in <module> 
File "/opt/Python/3.7.1/lib/python3.7/ssl.py", line 98, in <module> 
import _ssl # if we can't import it, let the error propagate 
ModuleNotFoundError: No module named '_ssl'

Solution:

Verify that Python was installed correctly from source following the Installing Python steps in the Posit Connect admin guide, including the steps to install pip and virtualenv.

Ensure that you defined the VERSION and PY_VERSION environment variables with the desired version of Python when following the installation steps.

Ensure that Python is installed in /opt/Python/2.x.x, or /opt/Python/3.x.x depending on the version of Python that you installed.

You can verify that your Python installation is working by running the following commands to import the SSL library (for Python 3.7.1 in this example):

$ /opt/Python/3.7.1/bin/python
Python 3.7.1 (default, Nov 29 2018, 16:28:02)
[GCC 4.8.4] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> import ssl
>>>

Version errors at startup when using Python 2 environments

Note: Starting in the 2022.03.0 release, the minimum Python version supported by Posit Connect is now 3.5. Configuration files that include Python 2, or Python 3 versions prior to 3.5, will cause an error during Connect startup.

Error:

The following error can occur during Posit Connect startup if you are using a newer version of virtualenv.

2020/02/10 15:59:21 Failed to get version of 'virtualenv' from the
output of: '/opt/Python/2.7.15/bin/python2.7 -m virtualenv --version',
output was '', error was 'virtualenv 20.0.1 from
/opt/Python/2.7.15/lib/python2.7/site-packages/virtualenv/__init__.pyc

The reason for this error is that virtualenv versions 20 and greater introduced a change that causes issues during startup with how Posit Connect detects Python environments. The result is that Python 2 installations will not be detected correctly by Posit Connect.

Solution:

A workaround is to downgrade to virtualenv to a compatible version less than version 20 by running the following command:

sudo /opt/Python/X.Y.Z/bin/pip install virtualenv<20

where X.Y.Z is the version of Python you are using with Posit Connect.

Wrong version of Python is used when rending Jupyter Notebooks

Error:

This error will usually manifest by a Jupyter Notebook in Connect not having the dependencies you expect from the development environment. You can confirm this by adding the following lines as part of the notebook and generating the report again in Posit Connect

import sys
sys.prefix

The expect output should be: 

/opt/rstudio-connect/mnt/app/python/env

When this error happens you will see something different, for example:

/opt/python/3.7.6

Solution:

This happens when the ipykernel Python package is installed in the Python installation used by Posit Connect (/opt/python/3.7.6) in this example.

To solve this remove the he ipykernel package and remove any Python environments that were affected by this. In this example we remove all Python Environments, this will be generated by Posit Connect again.

/opt/python/3.7.6/bin/pip uninstall ipykernel
rm -rf /var/lib/rstudio-connect/python-environments/