Troubleshooting

Common issues and their solutions.

Installation Issues

“pip install hostify” fails

Problem: Installation fails with error messages.

Solutions:

Update pip:
```
python -m pip install --upgrade pip
```

Use Python 3.9+:

python --version  # Should be 3.9 or higher

Try with –user flag:
```
pip install --user hostify
```

Import Error

Problem: ModuleNotFoundError: No module named 'hostify'

Solutions:

Verify installation:
```
pip show hostify
```
Check Python environment:
```
which python
which pip
```

Reinstall:

pip uninstall hostify
pip install hostify

Configuration Issues

“Cloudflare API token not found”

Problem: Error message about missing API token.

Solutions:

Set environment variable:

# Linux/Mac
export CF_API_TOKEN="your_token"

# Windows PowerShell
$env:CF_API_TOKEN="your_token"

Pass token directly:

Host(
    domain="app.example.com",
    port=3000,
    api_token="your_token_here"
).serve()

Verify token is set:

# Linux/Mac
echo $CF_API_TOKEN

# Windows PowerShell
echo $env:CF_API_TOKEN

“No Cloudflare accounts found”

Problem: API token doesn’t have correct permissions.

Solution:

Create a new token with these permissions:

Account → Cloudflare Tunnel → Edit
Zone → DNS → Edit
Zone → Zone → Read

See Installation for detailed instructions.

“Zone not found for domain”

Problem: Domain is not configured in Cloudflare.

Solutions:

Add domain to Cloudflare:
- Go to Cloudflare dashboard
- Click “Add a Site”
- Follow the setup wizard
Update nameservers:
- Point your domain’s nameservers to Cloudflare
- Wait for DNS propagation (can take up to 24 hours)
Verify domain is active:
- Check Cloudflare dashboard
- Domain status should be “Active”

Server Issues

“No server found on port X”

Problem: Hostify can’t connect to your local server.

Solutions:

Start your application first:

# Terminal 1: Start your app
python app.py

# Terminal 2: Run Hostify
python host.py

Verify server is running:

# Linux/Mac
lsof -i :3000

# Windows
netstat -ano | findstr :3000

Test server locally:

Open browser and visit http://localhost:3000
Check firewall:

Ensure localhost connections are allowed

“Port already in use”

Problem: The port you’re trying to use is occupied.

Solutions:

Find what’s using the port:

# Linux/Mac
lsof -i :3000

# Windows
netstat -ano | findstr :3000

Kill the process:

# Linux/Mac
kill -9 <PID>

# Windows
taskkill /PID <PID> /F

Use a different port:

Host(domain="app.example.com", port=3001).serve()

Connection Issues

Site shows 404 or “Not Found”

Problem: Domain loads but shows 404 error.

Solutions:

Wait for tunnel to connect:

Wait 30-60 seconds after starting Hostify
Check server is responding:
```
curl http://localhost:3000
```
Verify DNS propagation:
```
nslookup app.example.com
```
Check Cloudflare dashboard:
- Verify tunnel is active
- Check DNS record exists

“Tunnel process stopped unexpectedly”

Problem: Tunnel keeps disconnecting.

Solutions:

Check internet connection:

Ensure stable internet connectivity
Check cloudflared logs:

Look for error messages in the output
Restart Hostify:

Press Ctrl+C and run again
Update Hostify:
```
pip install --upgrade hostify
```

Site loads slowly

Problem: Website takes a long time to load.

Solutions:

Check local server performance:

Test http://localhost:3000 directly
Optimize application:
- Compress images
- Minify CSS/JS
- Enable caching
Check hardware resources:

Monitor CPU/RAM usage on host machine
Use production server:

Replace development servers with Gunicorn/uWSGI

Cleanup Issues

“Failed to delete tunnel”

Problem: Cleanup fails when stopping Hostify.

Solutions:

Manual cleanup via Cloudflare dashboard:
- Go to Zero Trust → Networks → Tunnels
- Delete orphaned tunnels manually
Check API token permissions:

Ensure token has “Edit” permission for Tunnels
Ignore if tunnel was already deleted:

This warning is usually harmless

DNS record not deleted

Problem: DNS record remains after stopping.

Solutions:

Manual deletion:
- Go to Cloudflare dashboard
- Navigate to DNS settings
- Delete the CNAME record
Verify API token permissions:

Ensure token has “Edit” permission for DNS

Platform-Specific Issues

Windows: “cloudflared.exe not found”

Problem: Windows can’t find the cloudflared binary.

Solutions:

Check antivirus:

Antivirus may be blocking the download
Manual download:

Download from https://github.com/cloudflare/cloudflared/releases
Add to PATH:

Place cloudflared.exe in a directory in your PATH

Linux: Permission denied

Problem: Permission errors when running Hostify.

Solutions:

Check file permissions:
```
chmod +x ~/.hostify/cloudflared
```

Run with proper permissions:

# Don't use sudo unless necessary
python host.py

macOS: “cloudflared cannot be opened”

Problem: macOS security blocks cloudflared.

Solutions:

Allow in Security & Privacy:
- System Preferences → Security & Privacy
- Click “Allow Anyway” for cloudflared

Remove quarantine attribute:

xattr -d com.apple.quarantine ~/.hostify/cloudflared

Getting Help

If you’re still experiencing issues:

Check GitHub Issues:

https://github.com/yuvrajarora1805/hostify/issues
Create a new issue:

Include:
- Python version (python --version)
- Hostify version (pip show hostify)
- Operating system
- Full error message
- Steps to reproduce

Enable debug logging:

import logging
logging.basicConfig(level=logging.DEBUG)

from hostify import Host
Host(domain="app.example.com", port=3000).serve()

Common Error Messages

Quick reference for error messages:

Error Message	Solution
“Domain is required”	Provide a domain parameter
“Either ‘port’ or ‘path’ must be specified”	Specify either port OR path
“Cannot specify both ‘port’ and ‘path’”	Use only one: port OR path
“Invalid port”	Use port between 1-65535
“Path does not exist”	Check the path to your static files
“Path is not a directory”	Path must point to a directory, not a file
“Failed to create tunnel”	Check API token and permissions
“Failed to create DNS record”	Verify domain is in Cloudflare