Troubleshooting

This guide helps you identify and resolve common issues with Safety Firewall. If you encounter problems during installation, configuration, or daily usage, the solutions here should help you get back

Verifying Installation

Problem: Command Not Found

If you see safety: command not found or similar errors:

1. Verify that Safety CLI is installed:

   pip list | grep safety-cli

2. Ensure the installation directory is in your PATH:

   echo $PATH

3. Reinstall Safety CLI if needed:

   pip install --upgrade safety-cli

Problem: "No such command" for Firewall Commands

If you see Error: No such command 'init' or Error: No such command 'firewall':

1. Verify that you're authenticated:

   safety auth status

2. If not authenticated, log in:

   safety auth login

3. Verify that your account has the Firewall feature enabled in Safety Platform

If you're logged in but still can't access Firewall commands, your organization may not have the Firewall feature enabled. Contact your Safety administrator or reach out to support.

Alias Configuration Issues

Problem: Package Manager Not Aliased

If which pip doesn't show pip is aliased to safety pip:

1. Reload your shell configuration:

   source ~/.safety/.safety_profile # or ~/.bashrc, ~/.zshrc, etc.

2. If that doesn't work, check the alias in your profile file:

   grep -r "alias pip=" ~/.profile ~/.bashrc ~/.zshrc 2>/dev/null

3. If the alias is missing, run the installation again:

   safety init

On Windows, we recommend restarting your terminal after installation to ensure the alias takes effect.

Alias Not Working After System Restart

If aliases stop working after restarting your system:

1. Check which shell you're using:

   echo $SHELL

2. Ensure Safety added aliases to the correct profile file for your shell

3. Add the source command to your shell's startup file if needed

On macOS or Linux, you can add source ~/.safety/shell/profile.sh to your shell's startup file to ensure aliases are always loaded.

Authentication Issues

Unable to Authenticate

If you're having trouble authenticating:

1. Ensure you have a valid Safety account

2. Check your internet connection

3. Try authenticating with the verbose flag:

   safety auth login --verbose

4. If the browser doesn't open automatically, manually copy and paste the URL from the terminal

Authentication Unexpectedly Fails

If you suddenly lose authentication:

1. Check your authentication status:

   safety auth status

2. Re-authenticate if needed:

   safety auth login

3. Check if your organization's API key has been rotated (for organization admins)

Firewall Uninstallation Issues

Unable to Uninstall Firewall

If safety firewall uninstall fails with "No such command":

1. First, ensure you're authenticated:

   safety auth login

2. If still unable to uninstall, manually remove the aliases:

   • Check your shell profile files (~/.bashrc, ~/.zshrc, etc.) for Safety aliases

   • Remove the Safety-related lines

   • Delete the ~/.safety directory:

     rm -rf ~/.safety

Manually uninstalling should be a last resort. This process will remove all Safety configuration from your system.

Package Installation Issues

Slow Package Installation

If package installations through Safety Firewall are slower than expected:

1. This is normal behaviour in the current version of Safety Firewall

2. Future versions will improve performance by streaming packages while analyzing them

The slight increase in installation time is a trade-off for the security benefits of preventing vulnerable or malicious packages from entering your system.

Unexpected Blocking of Packages

If legitimate packages are being blocked:

1. Check your organization's policies in Safety Platform

2. Look for overly restrictive rules that might be causing false positives

3. Consider temporarily modifying the policy to use warnings instead of blocks

4. If the package is incorrectly flagged, report it to Safety support

Package Not Available on the Public Index

A vendor may publish a package only to its own index and never to public PyPI or npm. The Safety index proxies the public registries, so installing a package that was never published publicly fails to resolve.

An allow rule does not fix this. Allow rules govern whether Safety permits a package it can see, and this package is absent from the index rather than blocked. An allow rule for a name nobody has published also stays in place if someone later registers that name on the public registry.

Adding the vendor's index alongside the Safety index is the wrong fix, and it fails differently in pip and in uv. Recipes for both follow. npm has no equivalent of --extra-index-url and resolves each package from one registry chosen by its scope, so it is not covered here.

Each one bypasses Safety's shell alias with command. In a configured shell pip routes through Safety, and the wrapper strips any --index-url or -i whose value does not point at the Safety index before pip sees it, then sets PIP_INDEX_URL back to the Safety index. Typing the recipe without the bypass resolves against the Safety index again, which is the failure this section works around. \pip or the binary's absolute path work the same way as command pip.

pip. Do not use --extra-index-url. pip queries all configured indexes and installs the highest version it finds, so a name published on both the vendor index and the public registry can resolve to either one. Install from the vendor's index instead, which replaces the index for that command:

command pip install --index-url <vendor-index-url> <package>

--index-url also routes the install's dependencies through the vendor index, so dependencies that index does not carry need to be installed separately. It replaces the primary index only, so an extra-index-url from any pip.conf or from PIP_EXTRA_INDEX_URL still applies. Remove those first.

uv. The pip recipe does not carry over. --index-url is deprecated in uv and maps to the default index, and neither it nor --default-index displaces the Safety index entry, because that entry is not the default index. Under uv, adding the vendor index with --index or a project uv.toml entry gives it higher priority than the Safety index for every name it carries, so it can shadow packages the Safety index serves. To resolve a single install from the vendor index, ignore your uv configuration for that command:

command uv pip install --no-config --default-index <vendor-index-url> <package>

--no-config skips configuration files only. Environment variables that add a package source, such as UV_INDEX, UV_EXTRA_INDEX_URL and UV_FIND_LINKS, still apply. Unset them first.

For a project, pin the vendor package to the vendor index instead of adding a competing index. explicit = true restricts an index to the packages that name it in tool.uv.sources, so it is consulted for those names only and cannot shadow anything else:

[[tool.uv.index]]
name = "vendor"
url = "<vendor-index-url>"
explicit = true

[tool.uv.sources]
vendor-package = { index = "vendor" }

An install that bypasses the alias is not checked against your policies at install time.

To have vendor or private registries governed by Safety Firewall, contact Safety support.

Codebase Issues

Codebase Not Appearing in Platform

If your codebase doesn't appear in Safety Platform after configuration:

1. Verify the codebase is properly initialized:

   ls -la | grep .safety-project.ini

2. Ensure you've run a scan at least once:

   safety scan

3. Check that you're authenticated with the correct organization:

   safety auth status

Automatic Scans Not Working

If automatic scans aren't running after package installations:

1. Verify that you're in a properly configured codebase directory

2. Check the .safety-project.ini file for any configuration issues

3. Verify package manager alias is working correctly (use which pip)

4. Run a manual scan to check if scanning works at all:

   safety scan --verbose

Platform Connection Issues

CLI Can't Connect to Platform

If the CLI can't connect to Safety Platform:

1. Check your internet connection

2. Verify your authentication:

   safety auth status

3. Check for proxy or firewall issues in your network

4. Try with the verbose flag to see more details:

   safety scan --verbose

Getting Additional Help

If you're still experiencing issues:

1. Run commands with the --verbose flag to get more detailed output

2. Check the Safety logs (located in ~/.safety/logs/)

3. Contact Safety support at [e-mail] with:

   • Command output (including any error messages)

   • Log contents

   • Your operating system and version

   • Your Safety CLI version (safety --version)