SC1091 — Not following source file: fix in 30 seconds

Problem

SC1091 fires whenever ShellCheck encounters `source path/to/file` (or `. path/to/file`) and cannot resolve the target. The most common causes are dynamic paths (`source "$HOME/.config/foo"`), files that live outside the analyzed directory, and CI environments where the dependency isn't checked out. The risk isn't the sourced file — it's that ShellCheck can't lint the variables and functions it defines, so genuine bugs further down may go unreported.

Bad

#!/usr/bin/env bash
source ../shared/lib.sh   # ShellCheck: SC1091, can't follow

Good

#!/usr/bin/env bash
# shellcheck source=../shared/lib.sh
source ../shared/lib.sh

# Or, when the path is dynamic, point at a representative file:
# shellcheck source=src/lib/defaults.sh
source "$CONFIG_DIR/defaults.sh"

Explanation

The `# shellcheck source=` directive tells ShellCheck where to find the file relative to the current script. Use the real path when it is static; use a representative file when it is dynamic. Never blanket-disable SC1091 — you'll lose downstream type information.

Related

SC1090

When It Matters

ShellCheck found a literal path in a source line but could not open the file, so everything that file defines is unknown to the rest of the analysis. That usually means the path is relative to the runtime working directory rather than to the script, which is also a runtime bug waiting to happen: run the script from another directory and the source fails. So the warning frequently points at a real fragility, not just an analysis gap.

Second Example

Exceptions

Sourcing a file that only exists at runtime — a generated environment file, /etc/os-release, a virtualenv activate script — cannot be resolved at check time. Use "# shellcheck source=/dev/null" for those and keep a real source= directive everywhere the file is in the repository.

Faq