Troubleshooting

Troubleshooting#

Regolith is a useful tool, but its somewhat complex compilation flow leaves room for user error. This page will explain solutions to common mistakes, as well as guide you through more complex debugging strategies.

General Debugging Tips#

Reading the Console#

Regolith runs in a terminal, providing valuable output during its execution. If something goes wrong, the console logs will often contain warnings, errors, or other helpful details about the issue.

Familiarize yourself with the console output and look for keywords like “warning” or “error” to identify problems. Reading the log carefully is often the first step in diagnosing an issue.

Checking Your Version#

Regolith is a living, breathing application, which is receiving numerous updates. You can directly install the latest version of Regolith, or watch out for the “A new Version is Available” messages in the console output.

Common Issues#

Regolith Command Not Recognized#

If you see an error like this when trying to run Regolith:

regolith : The term 'regolith' is not recognized as the name of a cmdlet, function, script file,
or operable program.

Check the spelling of the name, or if a path was included, verify that the path is correct and
try again.

The most common cause of this issue is incorrect installation. Here are some troubleshooting tips:

  1. Restart Your Terminal: Close the terminal or shell you’re using and reopen it. Then try running the regolith command again.

  2. Switch Terminals: Try a different shell. For example gitbash or vscode instead of powershell.

  3. Try reinstalling Regolith.

  4. Use the Stand-Alone Executable: If you cannot get Regolith installed, you may download the stand-alone executable, and place it in your project

Crash When Running#

The most common reason Regolith will crash is from a broken filter. The first step in debugging, is identifying which filter is failing. You can do so by navigating to the Regolith output log, and finding which filter caused the crash.

Filter errors will be printed like [error][filter] ... .

Where filter will be replaced with the name of the filter that had an error.

Dependency Not Found#

If Regolith cannot find a required dependency, you’ll see an error like:

[+] ... not found, download and install it from ...

This means the filter you’re trying to use depends on a runtime or library that is missing from your system.

Example errors:

  • Python [+]: Python not found, download and install it from https://www.python.org/downloads/

  • NodeJS [+]: NodeJS not found, download and install it from https://nodejs.org/en/