Skip to main content

​
Verification & diagnostics

Use these steps to confirm Safe Chain is installed and working before investigating further.

​
Check installed version

safe-chain --version

​
Verify shell integration

Run the verification command for your package manager: 
npm safe-chain-verify
pnpm safe-chain-verify
pip safe-chain-verify
uv safe-chain-verify
Expected output: OK: Safe-chain works!

​
Test malware blocking

Verify that malware detection is active by attempting to install a test package that is flagged as malware: 
npm install safe-chain-test
Safe Chain should block the installation. If the package installs successfully, see Malware not being blocked below.

​
Enable verbose logging

Get detailed diagnostic output for any package manager command: 
npm install express --safe-chain-logging=verbose
Or set it globally for the current terminal session: 
export SAFE_CHAIN_LOGGING=verbose
npm install express

​
Common issues

Symptom: Test malware packages (e.g. safe-chain-test) install successfully when they should be blocked.Most common cause: The package is already cached in your package manager’s local store. Safe Chain intercepts network requests to the registry through its proxy. When a package is cached locally, the package manager skips the network request and bypasses the proxy.Resolution:
1

Clear your package manager cache

# npm
npm cache clean --force

# pnpm
pnpm store prune

# yarn (classic)
yarn cache clean

# yarn (berry / v2+)
yarn cache clean --all

# bun
bun pm cache rm
Cache clearing removes all cached packages. Subsequent installs will re-download packages from the registry, which may increase build times in CI/CD environments.
2

Remove local installation artifacts (optional)

rm -rf node_modules
3

Re-test malware blocking

npm install safe-chain-test    # Should be blocked
Symptom: Running npm (or another wrapped command) shows the original tool instead of the Safe Chain-wrapped version.First step: Restart your terminal. This is the most common fix.Verify the alias is active:
type npm
Expected output: npm is a functionIf still not working, check that your shell’s startup file sources Safe Chain scripts from ~/.safe-chain/scripts/:
ShellStartup file
Bash~/.bashrc
Zsh~/.zshrc
Fish~/.config/fish/config.fish
PowerShell / PowerShell Core$PROFILE
Symptom: The safe-chain binary is not found after installation.First step: Restart your terminal.Check that ~/.safe-chain/bin is in your PATH:
echo $PATH
The output should contain ~/.safe-chain/bin.If the issue persists, re-run the installation script.
Symptom: When opening PowerShell you see an error similar to:
. : File C:\Users\<username>\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1 cannot be loaded because
running scripts is disabled on this system.
CategoryInfo          : SecurityError: (:) [], PSSecurityException
FullyQualifiedErrorId : UnauthorizedAccess
Cause: Windows PowerShell’s default execution policy (Restricted) blocks all script execution, including Safe Chain’s initialization script that is sourced from your PowerShell profile.Resolution:
1

Set the execution policy to allow local scripts

Open PowerShell as Administrator and run:
Set-ExecutionPolicy -ExecutionPolicy RemoteSigned
RemoteSigned allows local scripts (like Safe Chain’s) to run without signing, while requiring downloaded scripts to be signed by a trusted publisher. This is Microsoft’s recommended execution policy for client computers.
2

Restart PowerShell

Verify that the error is resolved.
Symptom: Safe Chain commands are still active after running the uninstall script.Resolution:
1

Run teardown (if the binary still exists)

safe-chain teardown
2

Restart your terminal

Check whether the aliases are gone.
3

Manually edit your shell config file if aliases persist

Open the relevant startup file and remove any lines that source scripts from ~/.safe-chain/scripts/:
ShellStartup file
Bash~/.bashrc
Zsh~/.zshrc
Fish~/.config/fish/config.fish
PowerShell / PowerShell Core$PROFILE
4

Restart your terminal again

The original commands should now be restored.

​
Manual cleanup

The install and uninstall scripts handle these steps automatically. Use the commands below only if automatic cleanup fails.

​
Remove npm global installation

npm uninstall -g @aikidosec/safe-chain

​
Remove installation directory

rm -rf ~/.safe-chain

​
Clean shell configuration files

Manually remove Safe Chain entries from your shell’s startup file:
ShellStartup file
Bash~/.bashrc
Zsh~/.zshrc
Fish~/.config/fish/config.fish
PowerShell / PowerShell Core$PROFILE
Look for and remove lines that source scripts from ~/.safe-chain/scripts/ or define Safe Chain wrapper functions.

​
Reporting issues

If you are still experiencing problems after following this guide:
  1. Visit GitHub Issues
  2. Include the following information:
    • Operating system and version
    • Shell type and version
    • Output of safe-chain --version
    • Output of the relevant safe-chain-verify command
    • Verbose logs from the failing command (append --safe-chain-logging=verbose)

Build docs developers (and LLMs) love

Get started for freeTalk to us