Security Troubleshooting

Quick Start

Most security issues can be resolved by running:

bb secure status
This command checks your certificates and trust store status, often suggesting specific solutions for any problems found.

Common Issues

Browser Security Warnings

Warning messages like "Your connection is not private" or "Invalid certificate"

Possible causes:

  • Certificate not in system trust store
  • Expired certificate
  • Trust store update needed

Solutions:

  1. Check certificate status:
    bb secure status
  2. Reinstall certificate if needed:
    bb secure trust
  3. Restart your browser after changes

Connection Errors

Errors like "Connection refused" or "Cannot connect to BB API"

Possible causes:

  • TLS configuration mismatch
  • Certificate file permissions
  • Port conflicts

Solutions:

  1. Verify TLS status:
    bb secure status
  2. Check API status:
    bb status
  3. Restart BB API:
    bb stop bb start

Trust Store Problems

Issues with system certificate trust or permission denied errors

Possible causes:

  • Insufficient permissions
  • Trust store corruption
  • System security policies

Solutions:

  1. Run commands with administrator privileges
  2. Check trust store status in system tools
  3. Manually verify certificate installation

See the Trust Store Guide for platform-specific steps.

Platform-Specific Issues

Windows

  • Certificate Manager (certmgr.msc) access denied
  • Windows Defender SmartScreen warnings
  • Trust store updates not reflecting

Run Command Prompt or PowerShell as Administrator when using BB security commands.

macOS

  • Keychain Access permission prompts
  • Gatekeeper blocking certificate installation
  • System Integrity Protection conflicts

Enter your login password when prompted for Keychain Access.

Linux

  • Distribution-specific certificate paths
  • System trust store update commands
  • Permission issues with certificate files

Use sudo when required for trust store operations.

Advanced Troubleshooting

Manual Certificate Verification

# Check certificate details
bb secure inspect

# Verify certificate chain
bb secure verify

# Test API connection
bb secure test

Certificate Renewal

If you're experiencing issues after certificate expiration:

# Force certificate renewal
bb secure renew

# Verify new certificate
bb secure status

Trust Store Reset

For persistent trust store issues, you can reset and reinstall:

# Remove from trust store
bb secure untrust

# Reinstall certificate
bb secure trust

Related Documentation

Still Having Issues?

If you're still experiencing problems after trying these solutions:

  1. Check the logs:
    bb logs --api
  2. Review the GitHub Issues for similar problems
  3. Create a new issue with your bb secure status output and logs