Troubleshooting

CLI Build Error (ModuleNotFoundError)

Issue Description

When compiling the project via an external system terminal (Command Line Interface) using pio run, the build might crash during the final linking stage with the following error:

*** [.pio/build/ttgo-lora32-v21/firmware.elf] ModuleNotFoundError: No module named 'SCons.Tool.FortranCommon'

Interestingly, this error does not occur when triggering the build inside the integrated VS Code PlatformIO IDE.

Root Cause

This behavior is caused by a Python environment collision on your local Linux system.

Inside the IDE (Success): VS Code automatically sandboxes the execution path. It activates PlatformIO's isolated virtual environment (located at ~/.platformio/penv/), ensuring that only the internally shipped, compatible dependencies are used.
Inside the System Terminal (Failure): When calling pio globally, your shell utilizes the system's global Python environment. If global Python packages or system-wide SCons modules are present (e.g., installed via apt, dnf, or pacman), they collide with the PlatformIO Core engine. This breaks internal lookup paths, causing the compilation to miss the required FortranCommon module during the binary linking process.

Solution

To resolve this issue permanently and ensure the CLI operates with the exact same isolation as the IDE, you must force your terminal to use PlatformIO's dedicated virtual environment binary.

Option 1: Configure Shell Aliases (Recommended)

Add an explicit alias to your shell configuration file to redirect global calls to the virtual environment binary.

Open your shell configuration file (e.g., ~/.bashrc or ~/.zshrc):
```
nano ~/.bashrc
```

Append the following lines at the very bottom of the file:

# Force the pio command to use PlatformIO's isolated virtual environment
alias pio="~/.platformio/penv/bin/pio"
alias platformio="~/.platformio/penv/bin/platformio"

Save the file and reload your current terminal session to apply the changes:
```
source ~/.bashrc
```

Option 2: Manually Activate the Virtual Environment

Alternatively, you can manually bootstrap the PlatformIO virtual environment inside your active terminal instance before running build tasks:

source ~/.platformio/penv/bin/activate

(Once activated, your terminal prompt will typically show a (penv) prefix, indicating that the isolated environment is active).

2.5 KiB Originalformat Blame Verlauf