Appendix B — Appendix: Troubleshooting Guide

B.1 Common Installation and Configuration Issues

The errors below are the ones that come up most often when setting these tools up, grouped by what you were trying to do at the time. Each entry says what to try and why the problem happens, since the second part is usually what stops it recurring.

B.1.1 Python Environment Issues

B.1.1.1 Virtual Environment Won’t Activate (uv / venv)

Issue: activate does nothing, or the packages you installed aren’t found afterwards.

Solution:

  1. Windows: Activate.ps1 fails with “running scripts is disabled on this system” until you allow local scripts once, with Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser. In cmd.exe the file to run is .venv\Scripts\activate.bat, not the .ps1
  2. macOS/Linux: the command is source .venv/bin/activate. Running .venv/bin/activate without source starts a subshell that exits immediately, which looks like nothing happening
  3. Check which Python you actually got: python -c "import sys; print(sys.executable)". If the path isn’t inside your .venv, the activation didn’t take
  4. After moving or renaming the project folder, delete .venv and recreate it. A virtual environment records absolute paths and doesn’t survive being moved

Why this happens: activation is only a change to environment variables in the current shell — mostly PATH. Anything that starts a fresh shell, or any command that doesn’t inherit those variables, gets the system Python instead.

B.1.1.2 Conda Environment Activation Problems

Issue: Unable to activate conda environments or “conda not recognised” errors.

Solution:

  1. Windows:
    • Ensure Conda is properly initialised by running conda init in the Miniforge (or Anaconda) Prompt
    • If using PowerShell, you may need to run Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser. Scoping it to your own user account is enough to let conda’s activation script run and avoids changing the policy machine-wide
    • Verify the PATH variable includes the Conda directories: C:\Users\<username>\miniforge3\Scripts and C:\Users\<username>\miniforge3 (substitute anaconda3 if you installed Anaconda)
  2. macOS/Linux:
    • Run source ~/miniforge3/bin/activate, or the appropriate path to your Conda installation
    • Add export PATH="$HOME/miniforge3/bin:$PATH" to your .bashrc or .zshrc file
    • Restart your terminal or run source ~/.bashrc (or .zshrc)

Why this happens: Conda needs to modify your system’s PATH variable to make its commands available. Installation scripts sometimes fail to properly update configuration files, especially if you’re using a non-default shell.

B.1.1.3 Package Installation Failures

Issue: Error messages when attempting to install packages with pip or conda.

Solution:

  1. For conda:
    • Try specifying a channel: conda install -c conda-forge package_name
    • Update conda first: conda update -n base conda
    • Create a fresh environment if existing one is corrupted: conda create -n fresh_env python=3.13
  2. For pip or uv:
    • Ensure pip is updated: python -m pip install --upgrade pip
    • Refuse to build from source, so you find out immediately that no wheel exists for your platform: pip install --only-binary :all: package_name
    • If a package does have to compile on Windows, you need the Visual C++ Build Tools. If that’s the only reason you’d install them, check whether conda has the package instead

Why this happens: Dependency conflicts, network issues, or missing compilers for packages that need to build from source.

B.1.2 R and RStudio Configuration

B.1.2.1 Package Installation Errors in R

Issue: Unable to install packages, especially those requiring compilation.

Solution:

  1. Windows:
    • Install Rtools from the CRAN website
    • Ensure you’re using a compatible version of Rtools for your R version
    • Try install.packages("package_name", dependencies=TRUE)
  2. macOS:
    • Install XCode Command Line Tools: xcode-select --install
    • Use homebrew to install dependencies: brew install pkg-config
    • For specific packages with external dependencies (like rJava), install the required system libraries first
  3. Linux:
    • Install R development packages: sudo apt install r-base-dev (Ubuntu/Debian)
    • Install specific dev libraries as needed, e.g., sudo apt install libxml2-dev libssl-dev

Why this happens: Many R packages contain compiled code that requires appropriate compilers and development libraries on your system.

B.1.2.2 RStudio Display or Rendering Issues

Issue: RStudio interface problems, plot display issues, or PDF rendering errors.

Solution:

  1. Update RStudio to the latest version

  2. Reset user preferences: Go to Tools → Global Options → Reset

  3. For PDF rendering issues: Install LaTeX (TinyTeX is recommended):

    install.packages('tinytex')
tinytex::install_tinytex()

  4. For plot display issues: Try a different graphics device or check your graphics drivers

Why this happens: RStudio relies on several external components for rendering that may conflict with system settings or require additional software.

B.1.3 Git and GitHub Problems

B.1.3.1 Authentication Issues with GitHub

Issue: Unable to push to or pull from GitHub repositories.

Solution:

  1. Check that your SSH keys are properly set up:
    • Verify key exists: ls -la ~/.ssh
    • Test SSH connection: ssh -T git@github.com
  2. If using HTTPS:
    • GitHub no longer accepts password authentication for HTTPS
    • Set up a personal access token (PAT) on GitHub and use it instead of your password
    • Store the token in your operating system’s keychain rather than in a file: credential.helper manager on Windows, osxkeychain on macOS, libsecret on Linux. Avoid credential.helper store, which many guides recommend — it writes the token to ~/.git-credentials in plain text, and a PAT is as good as a password
  3. Platform-specific issues:
    • Windows: Ensure Git Bash is used for SSH operations or set up SSH Agent in Windows
    • macOS: Add keys to the keychain: ssh-add --apple-use-keychain ~/.ssh/id_ed25519. Older guides use the short flag -K, which was deprecated in macOS Monterey
    • Linux: Ensure ssh-agent is running: eval "$(ssh-agent -s)"

Why this happens: GitHub stopped accepting account passwords over HTTPS in 2021, so every push now needs either an SSH key or a token, and the error messages don’t always say which one you’re missing.

B.1.3.2 Git Merge Conflicts

Issue: Encountering merge conflicts when trying to integrate changes.

Solution:

  1. Understand which files have conflicts: git status
  2. Open conflicted files and look for conflict markers (<<<<<<<, =======, >>>>>>>)
  3. Edit files to resolve conflicts, removing the markers once done
  4. Mark as resolved: git add <filename>
  5. Complete the merge: git commit

Visual merge tools can help:

  • VS Code has built-in merge conflict resolution
  • Use git mergetool with tools like KDiff3, Meld, or P4Merge

Why this happens: Git can’t automatically determine which changes to keep when the same lines are modified in different ways.

B.1.4 Docker and Container Issues

B.1.4.1 Permission Problems

Issue: “Permission denied” errors when running Docker commands.

Solution:

  1. Linux:
    • Add your user to the docker group: sudo usermod -aG docker $USER
    • Log out and back in for changes to take effect
    • Alternatively, use sudo before docker commands
    • Security note: membership in the docker group is effectively equivalent to root access on the host, because anyone in the group can mount the host filesystem into a privileged container. Only add trusted users, and on multi-user machines consider running rootless Docker or Podman instead.
  2. Windows/macOS:
    • Ensure Docker Desktop is running
    • Check that virtualisation is enabled in BIOS (Windows)
    • Restart Docker Desktop

Why this happens: Docker daemon runs with root privileges, so users need proper permissions to interact with it.

B.1.4.2 Container Resource Limitations

Issue: Containers running out of memory or being slow.

Solution:

  1. Increase Docker resource allocation:
    • In Docker Desktop, go to Settings/Preferences → Resources
    • Increase CPU, memory, or swap allocations
    • Apply changes and restart Docker
  2. Optimise Docker images:
    • Use a -slim base image rather than the full one (Containerisation explains why -alpine is usually the wrong call for scientific Python)
    • Delete build tools and package caches in the same RUN layer that created them
    • Order your Dockerfile from least to most frequently changing, so a code edit doesn’t reinstall every dependency

Why this happens: By default, Docker may not be allocated sufficient host resources, especially on development machines.

B.1.5 Environment Conflicts and Management

B.1.5.1 Python Virtual Environment Conflicts

Issue: Multiple Python versions or environments causing conflicts.

Solution:

  1. Use environment management tools consistently:
    • Pick one per project — uv or conda — and stay with it
    • Inside a conda environment, install what you can with conda before falling back to pip, and don’t alternate between them
  2. Isolate projects completely:
    • Create separate environments for each project
    • Use clear naming conventions: conda create -n project_name_env
    • Document dependencies: uv pip freeze > requirements.txt, or conda env export --from-history > environment.yml (the flag matters — see Reproducible Environments)
  3. When conflicts are unavoidable:
    • Use Docker containers to fully isolate environments
    • Consider tools like pyenv to manage multiple Python versions

Why this happens: Python’s packaging system allows packages to be installed in multiple locations, and search paths can create precedence issues.

B.1.5.2 R Package Version Conflicts

Issue: Incompatible R package versions or updates breaking existing code.

Solution:

  1. Use the renv package for project-specific package management:

    install.packages("renv")
renv::init()      # Initialise for a project
renv::snapshot()  # Save current state
renv::restore()   # Restore saved state

  2. Install specific versions when needed:

    remotes::install_version("ggplot2", version = "3.3.3")

  3. For reproducibility across systems:

    • Consider using Docker with rocker images
    • Document R and package versions in your project README

Why this happens: R’s package ecosystem evolves quickly, and new versions sometimes introduce breaking changes.

B.1.6 IDE-Specific Problems

B.1.6.1 VS Code Extensions and Integration Issues

Issue: Python or R extensions not working properly in VS Code.

Solution:

  1. Python in VS Code:
    • Ensure proper interpreter selection: Ctrl+Shift+P → “Python: Select Interpreter”
    • Restart language server: Ctrl+Shift+P → “Python: Restart Language Server”
    • Check extension requirements: Python extension needs Python installed separately
  2. R in VS Code:
    • Install languageserver package in R: install.packages("languageserver")
    • Configure R path in VS Code settings
    • For plot viewing, install the httpgd package: install.packages("httpgd")

Why this happens: VS Code relies on language servers and other components that need proper configuration to communicate with language runtimes.

B.1.6.2 Jupyter Notebook Kernel Issues

Issue: Unable to connect to kernels or kernels repeatedly dying.

Solution:

  1. List available kernels: jupyter kernelspec list
  2. Reinstall problematic kernels:
    • Remove: jupyter kernelspec remove kernelname
    • Install for current environment: python -m ipykernel install --user --name=environmentname
  3. Check resource usage if kernels are crashing:
    • Reduce the size of data loaded into memory
    • Increase system swap space
    • For Google Colab, reconnect to get a fresh runtime

Why this happens: Jupyter kernels run as separate processes and rely on proper registration with the notebook server. They can crash if they run out of resources.

B.1.7 Platform-Specific Considerations

B.1.7.1 Windows-Specific Issues

  1. Path Length Limitations:
    • Enable long path support: in registry editor, set HKLM\SYSTEM\CurrentControlSet\Control\FileSystem\LongPathsEnabled to 1
    • Use the Windows Subsystem for Linux (WSL) for projects with deep directory structures
  2. Line Ending Differences:
    • Configure Git to handle line endings: git config --global core.autocrlf true
    • Use .gitattributes files to specify line ending behaviour per project
  3. PowerShell Execution Policy:
    • If scripts won’t run: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

B.1.7.2 macOS-Specific Issues

  1. Homebrew Conflicts:
    • Keep Homebrew updated: brew update && brew upgrade
    • If conflicts occur with Python/R: prefer conda/CRAN over Homebrew versions
    • Use brew doctor to diagnose issues
  2. XCode Requirements:
    • Many data science tools require the XCode Command Line Tools
    • Install with: xcode-select --install
    • Update with: softwareupdate --all --install --force
  3. System Integrity Protection Limitations:
    • Some operations may be restricted by SIP
    • For development-only machines, SIP can be disabled (not generally recommended)

B.1.7.3 Linux-Specific Issues

  1. Package Manager Conflicts:
    • Avoid mixing distribution packages with conda/pip when possible
    • Consider using --user flag with pip or isolated conda environments
    • For system-wide Python/R, use distro packages for system dependencies and virtual environments for project dependencies
  2. Library Path Issues:
    • If shared libraries aren’t found: export LD_LIBRARY_PATH=/path/to/libs:$LD_LIBRARY_PATH
    • Create .conf files in /etc/ld.so.conf.d/ for permanent settings
  3. Permission Issues with Docker:
    • If facing repeated permission issues, consider using Podman as a rootless alternative
    • Properly set up user namespaces if needed for production

B.2 Troubleshooting Workflow

When facing issues, follow this general troubleshooting workflow:

  1. Identify the exact error message - Copy the full message, not just part of it
  2. Search online for the specific error - Use quotes in your search to find exact phrases
  3. Check documentation - Official docs often have troubleshooting sections
  4. Try the simplest solution first - Many issues can be resolved by restarting services or updating software
  5. Isolate the problem - Create a minimal example that reproduces the issue
  6. Use community resources - Stack Overflow, GitHub issues, and Reddit communities can help
  7. Document your solution - Once solved, document it for future reference

Step 5 is the one people skip and the one that most often solves the problem on its own. Cutting a failure down to the smallest thing that still reproduces it usually tells you where it lives.