Shell Environment Best Practices

Your shell environment, specifcally your ~/.bashrc on ARC clusters controls which commands are available, how modules load, and whether tools like Open OnDemand and Slurm work correctly. Misconfiguring ~/.bashrc is one of the most common causes of hard to diagnose issues on ARC, including OOD job submissions failing, sbatch not being found, and modules not loading.

How ARC sets up your environment

When you log into an ARC cluster, the system sources /etc/bashrc, which inmturn loads all the scripts that set up Lmod, Slurm, and the rest of the cluster environment. ARC injects this block into your ~/.bashrc automatically:

# this is required for module to work
if [[ -f /etc/bashrc && ! $BASH_SOURCED ]]; then
    . /etc/bashrc
fi

This block must always run. It is required for modules, Slurm commands (sbatch, squeue, etc.), and Open OnDemand to work correctly.

A common mistake: early return guards

This pattern common in online guides and copied configs is this:

#  DO NOT place this before the ARC /etc/bashrc block
if [ -z "$PS1" ]; then
    return
fi

The intent is to skip ~/.bashrc in non-interactive shells. The problem is that non-interactive shells include:

Open OnDemand job submissions
SSH remote commands (e.g. ssh cluster 'sbatch myjob.sh')
Coding agents running SSH commands (e.g. Claude Code)

If this guard appears before the ARC /etc/bashrc block, it silently skips all of the cluster environment setup in those contexts. The result is errors like this maybe on Open Ondemand:

bash: line 1: sbatch: command not found

even though sbatch works fine in your normal interactive terminal.

The correct ~/.bashrc structure

# ARC-injected block, must come first, do not move or guard this:
if [[ -f /etc/bashrc && ! $BASH_SOURCED ]]; then
    . /etc/bashrc
fi

# --- Your customisations go below here ---
# module loads, environment variables, aliases for all shells

# --- Interactive-only customisations: prompt, display aliases ---
# Use  if [ -n "$PS1" ]  (note: -n not -z) to guard these
if [ -n "$PS1" ]; then
    alias ll='ls -lh'
    # PS1="..."  # custom prompt
fi

Note

If you want to guard interactive-only settings, use if [ -n "$PS1" ] (prompt IS set) rather than if [ -z "$PS1" ] (prompt is NOT set). This keeps the guard inside your customisations rather than wrapping the ARC setup block.

Diagnosing a broken environment

If OOD jobs fail or Slurm commands are not found, run these two tests from your laptop without logging into the cluster first:

Test 1 — non-interactive environment (what OOD sees):

ssh CLUSTER 'which sbatch; echo $PATH; sbatch --version'

Test 2 — login shell environment (what your terminal sees):

ssh CLUSTER 'bash -lc "which sbatch; echo $PATH; sbatch --version"'

Replace CLUSTER with a login node, e.g. tinkercliffs2.arc.vt.edu or owl3.arc.vt.edu

Result	Likely cause
Test 1 fails, Test 2 works	Early return guard or bad sourcing in `~/.bashrc`
Both fail	Deeper environment or account issue — contact ARC support
Both work	Issue is elsewhere — contact ARC support with both outputs

If Test 1 fails and Test 2 works, review your ~/.bashrc and remove any early return guards that appear before the ARC /etc/bashrc block.