Skip to content

9.1 Troubleshooting

In this session you learn:

  • about common pitfalls
  • about tools for identifying the root cause
  • other tips and techniques to stay on the happy path


General troubleshooting tips#

Identify what the error is and where it's coming from

  • An error reported in the IDE might arise from:

    • User code, an R package, or R itself
    • The RStudio IDE
  • How widespread is this issue?

    • Does it affect one user, the entire server, or the whole cluster?
  • Can you reproduce the problem?

  • Identify the root cause of the error

    • Any recent changes?
    • Specific users or groups involved?
    • Specific code being run?


Change one thing at a time to try and isolate the issue

Things RStudio Support looks at (and you should too):#

  • Log files
  • R
  • Local environment and environment variables

Common issues:

  • Licensing
  • Configuration
  • Authentication
  • Network issues

Log file locations#

  1. RStudio log files

    Product Log file
    RStudio Server Pro /var/lib/rstudio-server/monitor/log/rstudio-server.log
    Shiny Server Pro /var/log/shiny-server.log
    RStudio Connect /var/log/rstudio-connect.log
    Package Manager /var/log/rstudio-pm.log
  2. System log files

    Area Log file
    Server log files /var/log/syslog
    Authentication logs /var/log/auth.log
  3. For RStudio Connect deployment issues:

    You can view the generated deployment log in the R console, or retrieve from R using the rsconnect package:




Troubleshooting R#

R runs correctly#

  • Almost all RStudio products depend on R being installed successfully to run.
    • Look for errors related to R in the server logs
  • Can R be launched manually and can the user's code be run in R without any errors?
  • How was R installed?
grep configure R_HOME/etc/Makeconf


Are all necessary dependencies installed?

apt-get build-dep r-base
yum-builddep R

Are the permissions set correctly to allow r-x (read and execute) by all?

namei -l /path/to/R


Multiple versions of R#

Are there multiple versions of R on the system?

apt-get install mlocate
## locate

If so, see questions above for all versions in addition to checking that the expected version is loaded.

Troubleshooting the environment#

Local environment#

What operating system are you running on?

uname -a

cat /etc/*-release

Are you running with load balancing or in a virtual container such as Docker, etc?

Environment variables#

Does your setup rely on specific environment variables to be set correctly?

If so, are those set correctly in R as well as RStudio?

  • Proxy settings
  • Java
  • Database connections
  • System library path issues
    • For example, LD_LIBRARY_PATH, PATH, etc.

R pulls from several startup files


Look for any errors in the startup.

  • You can view the live log during startup using
tail -f /path/to/log

Read through the admin guides and make sure you have the correct formatting

Make sure you're on the right version of the product compared to the admin guide!


Expired licenses#


  • Things to try:

    • Check time and time zone timedatectl
    • Resync if needed, e.g. sudo hwclock -w
    • Restart
  • Deactivation tool:

  • Long-term solutions

    • Consider switching to offline setup
  • RStudio is working on improvements


  • Difficult for RStudio Support to troubleshoot as it depends on external configuration values unknown to us.

  • Does it work outside of the RStudio product?

    • Often possible to copy over working setup from other systems or services.
    • For RStudio Server Pro
    • pamtester utility lets you test outside RStudio systems.
sudo /usr/lib/rstudio-server/bin/pamtester \
  --verbose rstudio <username> authenticate
  • Check server log files including access.log files.
  • Check connections to any external authentication providers
    • Kerberos, Active Directory, etc.

Network issues#

Network issues are outsidet the scope of the RStudio support SLA.

This means we're limited on the help we can provide.

Things to check:

  • Connectivity
  • SSL / certificate
  • Firewall / security / proxy settings


Helpful resources#

RStudio documentation

Document Location
Admin guides / user guides
FAQs / articles
Shiny docs

Other resources

Document Location
RStudio Community
RViews blog
License deactivation app

Working with support#

Things that help:

  • Describe error messages / what users are seeing
  • Describe system information
    • Operating System
    • R version
    • product version
  • Attach:
    • server log files
    • configuration files
    • deployment logs

Getting help

Your turn#

Next complete the exercise.