20  Common Tasks & Troubleshooting

This chapter covers frequently asked questions and common problems.

WarningClaude Code

Claude Code excels at debugging—paste an error message and it can usually trace the cause and suggest a fix.

I’m getting this error and don’t understand it: [paste error message]. This is the code that caused it: [paste code or filename:line]. What’s happening?

Claude will read the error, examine your code, and explain what went wrong in plain language. Include both the error and the code—context helps Claude trace the issue much faster.

WarningClaude Code

Claude Code can help diagnose why previously working code suddenly breaks.

This script was working yesterday and now fails with: [error]. I didn’t change anything in the script. What could have changed?

Claude will investigate environment changes, package updates, or data differences that could explain the regression.

20.1 Conda

20.1.1 “command not found: conda”

macOS/Linux: Conda isn’t initialized in this shell session.

source ~/miniforge3/etc/profile.d/conda.sh
# Or for miniconda:
source ~/miniconda3/etc/profile.d/conda.sh

Add this to your ~/.zshrc or ~/.bashrc to make it permanent.

Windows: Open “Anaconda Prompt” or “Miniforge Prompt” instead of regular Command Prompt.

20.1.2 “Solving environment” is very slow

Conda’s dependency resolver can be slow with complex environments.

Solutions:

  1. Use mamba (faster drop-in replacement):

    conda install mamba -n base
mamba install package-name

  2. Create minimal environments:

    conda create -n project python=3.11 pandas numpy
# Instead of installing everything at once

  3. Use conda-forge channel consistently:

    conda config --add channels conda-forge
conda config --set channel_priority strict

20.1.3 Environment not activating in Positron

  1. Open Positron’s integrated terminal
  2. Manually activate: conda activate my-env
  3. Use Command Palette: “Python: Select Interpreter” → choose the environment

20.1.4 Recreating a broken environment

conda deactivate
conda env remove -n broken-env
conda env create -f environment.yml

20.2 renv

20.2.1 “The project is out-of-sync”

This warning means packages in your library don’t match renv.lock.

To see what’s different:

renv::status()

To sync library to lockfile (recommended):

renv::restore()

To update lockfile to match library:

renv::snapshot()

20.2.2 Package installation fails

Try clearing the cache and rebuilding:

renv::install("package-name", rebuild = TRUE)

For persistent issues:

# Check for system dependencies
renv::diagnostics()

# Install from a different repository
renv::install("package-name", repos = "https://cloud.r-project.org")

20.2.3 Starting fresh with renv

renv::deactivate()
rm -rf renv renv.lock .Rprofile
renv::init()

20.3 Git

20.3.1 “Updates were rejected because the remote contains work…”

Someone pushed while you were working.

git pull
# Resolve any conflicts if needed
git push

20.3.2 Accidentally committed large files

Remove from history (if not yet pushed):

git reset --soft HEAD~1
# Edit .gitignore to exclude the file
git add .gitignore
git commit -m "Fix gitignore"

If already pushed, use BFG or git-filter-branch (more complex).

20.3.3 Undo the last commit (keep changes)

git reset --soft HEAD~1

20.3.4 See what changed in a file

git log -p filename.R

20.3.5 Discard all uncommitted changes

git checkout -- .
# Or for all files including untracked:
git clean -fd

⚠️ This permanently deletes uncommitted work!

20.4 Claude Code

20.4.1 “Command not found” for conda in Claude Code

Claude Code runs in a non-interactive shell. Always source conda first:

source ~/miniforge3/etc/profile.d/conda.sh && conda activate my-env && python script.py

Document this pattern in your .claude/CLAUDE.md.

20.4.2 Claude doesn’t understand my project

Ensure .claude/CLAUDE.md exists and contains:

  • Project overview
  • Environment setup commands
  • Key file locations
  • Common workflows

20.4.3 Responses are generic or unhelpful

Provide more context:

  • Show the specific file or code
  • Explain what you’re trying to accomplish
  • Share error messages in full

Instead of: “Fix the bug”

Try: “In analysis.R line 45, I get ‘object x not found’. Here’s the relevant code: [paste code]. The data is loaded from data/data.csv.”

20.5 Positron

20.5.1 R not detected

  1. Check R is installed: R --version in terminal
  2. In Positron settings, search for “R Path” and set it explicitly
  3. Restart Positron

20.5.2 Python interpreter not showing

  1. Activate conda environment in terminal
  2. Command Palette → “Python: Select Interpreter”
  3. Click “Enter interpreter path” and navigate to the environment’s Python

20.5.3 Slow or unresponsive

  1. Close unused tabs
  2. Restart Positron
  3. Check if large objects are in memory (clear R/Python session)
  4. Check system memory usage

20.6 Quarto

20.6.1 “quarto: command not found”

macOS:

brew install quarto
# Or use full path:
/usr/local/bin/quarto render document.qmd

Windows: Ensure Quarto installer added it to PATH. Restart terminal.

20.6.2 Render fails with R errors

  1. Run the R code chunks manually to find the error
  2. Check that all packages are installed
  3. Ensure working directory is correct (use here package)

20.6.3 Render fails with Python errors

  1. Ensure correct conda environment is active

  2. Check Python interpreter in document YAML:

    jupyter: python3

20.7 General Workflow

20.7.1 How do I start working on a project?

cd project-directory
conda activate project-env  # if Python
positron .
# R activates renv automatically via .Rprofile

20.7.2 How do I end a work session?

git status                    # See what changed
git add .                     # Stage changes
git commit -m "Description"   # Commit
git push                      # Push to GitHub

20.7.3 How do I update all packages?

Python:

conda update --all
conda env export > environment.yml
git add environment.yml && git commit -m "Update packages"

R:

renv::update()
renv::snapshot()
git add renv.lock && git commit -m "Update R packages"

20.7.4 How do I share my project?

  1. Ensure environment.yml and renv.lock are up to date
  2. Write clear README with setup instructions
  3. Push to GitHub
  4. Share the repository URL

The collaborator then:

git clone https://github.com/user/project.git
cd project
conda env create -f environment.yml
# In R: renv::restore()

20.8 Getting Help

20.8.1 For tool-specific issues:

20.8.2 In Claude Code:

Just ask! Describe your problem with as much detail as possible.