Troubleshooting

Common Issues (All Platforms)

RuntimeError: Failed to create a default .NET runtime

If you encounter the following error:

RuntimeError: Failed to create a default .NET runtime, which would have been "mono" on this system.
Either install a compatible runtime or configure it explicitly via set_runtime or the PYTHONNET_*
environment variables (see set_runtime_from_env).

Solution: Set the Python.NET runtime environment variable to use CoreCLR:

Linux/macOS:

export PYTHONNET_RUNTIME=coreclr

To make this permanent, add the above line to your shell configuration file (e.g., ~/.bashrc, ~/.zshrc, or ~/.bash_profile).

Windows (Command Prompt):

set PYTHONNET_RUNTIME=coreclr

Windows (PowerShell):

$env:PYTHONNET_RUNTIME="coreclr"

To make this permanent on Windows, set it as a system environment variable through System Properties > Environment Variables.

Linux-Specific Issues

GUI Application Requirements

The SynapSpec GUI application requires a graphical desktop environment to run.

CLI-only systems: The GUI will not work on headless Linux servers or CLI-only installations. Use the CLI interface instead.
Desktop environments: The GUI works on Linux systems with desktop environments such as GNOME, KDE, XFCE, etc.

macOS-Specific Issues

App cannot be opened because the developer cannot be verified

Due to macOS Gatekeeper security settings, you might need to manually approve the application since it may not have an Apple Developer Code Signature.

Go to System Settings (or System Preferences).
Navigate to Privacy & Security.
Scroll down to the Security section.
Find the message regarding SynapSpec (e.g., “SynapSpec was blocked from use because it is not from an identified developer.”) and click the Open Anyway button.

Mono Framework Library Path Issue

SynapSpec may rely on the Mono framework. If you’ve installed Mono via Homebrew (brew install mono) and the application cannot find a necessary library, you might need to create a symbolic link.

Issue: The application expects the Mono library at /Library/Frameworks/Mono.framework/Versions/Current/lib/libmonosgen-2.0.dylib, but this path is missing.

Solution (Create a Symbolic Link):

Identify your Mono version: Check the version number of Mono installed by Homebrew in the /opt/homebrew/Cellar/mono/ directory. (Replace {version} in the commands below with your actual version, e.g., 6.12.0.182).

Create the necessary directory path:

sudo mkdir -p /Library/Frameworks/Mono.framework/Versions/Current/lib

Create the symbolic link (symlink) from the Homebrew installation path to the expected library path:

sudo ln -s /opt/homebrew/Cellar/mono/{version}/lib/libmonosgen-2.0.dylib /Library/Frameworks/Mono.framework/Versions/Current/lib/libmonosgen-2.0.dylib