Troubleshooting Guide

This guide provides solutions to common problems encountered when installing and using Hubio Sync.

Installation Issues
Runtime Issues
Platform-Specific Issues
Network Issues
Configuration Issues

Installation Issues

Command Not Found

Problem: After installation, running hubio-sync shows command not found.

Symptoms:

$ hubio-sync --version
bash: hubio-sync: command not found

Solutions:

1. Check Installation Path

Verify the binary was installed:

# macOS/Linux
ls -la /usr/local/bin/hubio-sync

# Check alternative locations
find /usr -name "hubio-sync" 2>/dev/null

2. Update PATH

Add the installation directory to your PATH:

# For bash
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# For zsh
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# For fish
set -Ua fish_user_paths /usr/local/bin

3. Reload Shell

Sometimes a simple shell reload fixes the issue:

# Reload current shell
exec $SHELL

# Or open a new terminal window

4. Verify Installation Method

Check how you installed:

# If installed via Homebrew (macOS)
brew list hubio-sync

# If installed via APT (Ubuntu/Debian)
dpkg -l | grep hubio-sync

# If installed via DNF (Fedora/RHEL)
rpm -qa | grep hubio-sync

Permission Denied

Problem: Binary exists but can’t be executed due to permissions.

Symptoms:

$ hubio-sync --version
bash: /usr/local/bin/hubio-sync: Permission denied

Solutions:

1. Check File Permissions

ls -l /usr/local/bin/hubio-sync
# Should show: -rwxr-xr-x (executable)

2. Add Execute Permission

sudo chmod +x /usr/local/bin/hubio-sync

3. Check Ownership

Ensure the file has correct ownership:

# Check current owner
ls -l /usr/local/bin/hubio-sync

# Fix ownership if needed (run as root)
sudo chown root:root /usr/local/bin/hubio-sync

4. SELinux Context (Linux)

If SELinux is enabled:

# Check SELinux status
getenforce

# Restore proper context
sudo restorecon -v /usr/local/bin/hubio-sync

# Or set executable context
sudo chcon -t bin_t /usr/local/bin/hubio-sync

Version Mismatch

Problem: Installed version doesn’t match expected version.

Symptoms:

$ hubio-sync --version
hubio-sync version 0.9.0  # Expected: 1.0.0

Solutions:

1. Check for Multiple Installations

# Find all hubio-sync installations
which -a hubio-sync

# Check which one is being used
type hubio-sync

2. Remove Old Versions

# Manual installation
sudo rm /usr/local/bin/hubio-sync

# Homebrew
brew uninstall hubio-sync && brew install hubio-sync

# APT
sudo apt remove hubio-sync && sudo apt install hubio-sync

# DNF
sudo dnf remove hubio-sync && sudo dnf install hubio-sync

3. Force Reinstall

# Download and run install script with --force
curl -sSL https://install.hubio.team/install-scripts/install.sh | bash -s -- --force

Installation Script Fails

Problem: Installation script exits with errors.

Common Causes:

1. Network Issues

# Test connectivity
curl -I https://install.hubio.team

# Use alternative DNS
sudo echo "nameserver 8.8.8.8" >> /etc/resolv.conf

2. Missing Dependencies

Ubuntu/Debian:

sudo apt update
sudo apt install curl ca-certificates

Fedora/RHEL:

sudo dnf install curl ca-certificates

macOS:

# Install Xcode Command Line Tools
xcode-select --install

3. Insufficient Disk Space

# Check available space
df -h /usr/local

# Clean up if needed
brew cleanup  # macOS
apt clean     # Ubuntu/Debian
dnf clean all # Fedora/RHEL

4. Firewall/Proxy Issues

# Configure proxy (if behind corporate firewall)
export https_proxy=http://proxy.company.com:8080
export http_proxy=http://proxy.company.com:8080

# Then retry installation
curl -sSL https://install.hubio.team/install-scripts/install.sh | bash

Runtime Issues

Configuration Not Found

Problem: Hubio Sync can’t find configuration file.

Symptoms:

Error: Configuration file not found at ~/.config/hubio-sync/config.toml

Solutions:

1. Create Default Configuration

# Create config directory
mkdir -p ~/.config/hubio-sync

# Generate default config
hubio-sync init --config ~/.config/hubio-sync/config.toml

2. Specify Config Path

# Use custom config location
hubio-sync --config /path/to/config.toml <command>

3. Check File Permissions

# Ensure config file is readable
chmod 600 ~/.config/hubio-sync/config.toml

Connection Refused

Problem: Cannot connect to data source.

Symptoms:

Error: Connection refused (os error 111)

Solutions:

1. Verify Service is Running

# Check if target service is accessible
ping <hostname>
telnet <hostname> <port>

# Example: Test MySQL connection
telnet mysql.example.com 3306

2. Check Firewall Rules

# Linux
sudo ufw status
sudo firewall-cmd --list-all

# macOS
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --getglobalstate

3. Verify Connection String

Double-check your configuration:

[source]
host = "correct-hostname.com"  # Not "locahost" typo
port = 3306                    # Correct port
username = "valid-user"

Platform-Specific Issues

macOS: “Cannot be opened because the developer cannot be verified”

Problem: macOS blocks unsigned binary.

Symptoms: Gatekeeper warning dialog when running hubio-sync.

Solutions:

1. Allow via System Preferences

Open System Preferences → Security & Privacy
Click “Open Anyway” next to the warning about hubio-sync
Enter admin password

2. Remove Quarantine Attribute

sudo xattr -d com.apple.quarantine $(which hubio-sync)

3. Whitelist via Command Line

sudo spctl --add $(which hubio-sync)

Windows: SmartScreen Warning

Problem: Windows Defender SmartScreen blocks execution.

Solutions:

1. Click “More info” then “Run anyway”

2. Add Exception

Open Windows Security
Go to Virus & threat protection → Manage settings
Add exception for hubio-sync.exe

Linux: AppArmor/SELinux Denials

Problem: Security policies block execution.

Check Logs:

# SELinux
sudo ausearch -m avc -ts recent | grep hubio

# AppArmor
sudo journalctl | grep apparmor | grep hubio

Solutions:

SELinux

# Temporarily set to permissive mode
sudo setenforce 0

# If that works, create policy
sudo ausearch -m avc -ts recent | grep hubio | audit2allow -M hubio-sync
sudo semodule -i hubio-sync.pp

# Re-enable enforcing mode
sudo setenforce 1

AppArmor

# Disable profile (temporary)
sudo aa-complain /usr/local/bin/hubio-sync

# Or create custom profile
sudo aa-logprof

Network Issues

SSL/TLS Certificate Errors

Problem: Cannot verify SSL certificates.

Symptoms:

Error: SSL certificate problem: unable to get local issuer certificate

Solutions:

1. Update CA Certificates

# Ubuntu/Debian
sudo apt update && sudo apt install ca-certificates
sudo update-ca-certificates

# Fedora/RHEL
sudo dnf install ca-certificates
sudo update-ca-trust

# macOS
# Certificates managed by Keychain - usually no action needed

2. Configure Custom CA Bundle

# Set environment variable
export CURL_CA_BUNDLE=/path/to/ca-bundle.crt

# Or in config.toml
[network]
ca_bundle = "/path/to/ca-bundle.crt"

Proxy Configuration

Problem: Requests fail behind corporate proxy.

Solutions:

1. Set Environment Variables

export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
export NO_PROXY=localhost,127.0.0.1,.local

2. Configure in config.toml

[network]
proxy = "http://proxy.company.com:8080"
no_proxy = ["localhost", "127.0.0.1"]

Configuration Issues

Invalid TOML Syntax

Problem: Configuration file has syntax errors.

Symptoms:

Error: TOML parse error at line 5, column 10

Solutions:

1. Validate TOML Syntax

Use an online TOML validator or:

# Install TOML linter
pip install toml

# Validate config
python -c "import toml; toml.load(open('config.toml'))"

2. Common Syntax Errors

# ❌ Wrong: Missing quotes
host = localhost

# ✓ Correct: Quoted string
host = "localhost"

# ❌ Wrong: Trailing comma in array
ports = [8080, 9090,]

# ✓ Correct: No trailing comma
ports = [8080, 9090]

Getting Further Help

If none of these solutions work:

Enable Debug Logging:

export RUST_LOG=debug
hubio-sync <command>

Collect System Information:

hubio-sync debug --system-info > debug.txt

Check Known Issues:
- GitHub Issues
- Release Notes
Contact Support:
- Microsoft Teams: Contact your team administrator for the Hubio Sync support channel
- Email: support@hubio.com

When reporting issues, please include:

Operating system and version
Hubio Sync version (hubio-sync --version)
Installation method (script, package manager, etc.)
Full error message
Steps to reproduce

Troubleshooting Guide

Table of Contents

Installation Issues

Command Not Found

1. Check Installation Path

2. Update PATH

3. Reload Shell

4. Verify Installation Method

Permission Denied

1. Check File Permissions

2. Add Execute Permission

3. Check Ownership

4. SELinux Context (Linux)

Version Mismatch

1. Check for Multiple Installations

2. Remove Old Versions

3. Force Reinstall

Installation Script Fails

1. Network Issues

2. Missing Dependencies

3. Insufficient Disk Space

4. Firewall/Proxy Issues

Runtime Issues

Configuration Not Found

1. Create Default Configuration

2. Specify Config Path

3. Check File Permissions

Connection Refused

1. Verify Service is Running

2. Check Firewall Rules

3. Verify Connection String

Platform-Specific Issues

macOS: “Cannot be opened because the developer cannot be verified”

1. Allow via System Preferences

2. Remove Quarantine Attribute

3. Whitelist via Command Line

Windows: SmartScreen Warning

1. Click “More info” then “Run anyway”

2. Add Exception

Linux: AppArmor/SELinux Denials

SELinux

AppArmor

Network Issues

SSL/TLS Certificate Errors

1. Update CA Certificates

2. Configure Custom CA Bundle

Proxy Configuration

1. Set Environment Variables

2. Configure in config.toml

Configuration Issues

Invalid TOML Syntax

1. Validate TOML Syntax

2. Common Syntax Errors

Getting Further Help