v2.1.4

[2.1.4] - 2026-03-16

Fixed

• 🐧 Linux EACCES Spawn Error: Fixed "spawn cloudflared EACCES" permission denied error on Linux
  • Binary now always has execute permissions verified and auto-repaired before spawning
  • ensureCloudflared() is called on every run, not just when the binary is missing
  • BinaryManager.validate() now checks execute permissions (X_OK), not just file existence
  • Auto-fixes permissions with chmod 755 if the binary exists but isn't executable
  • Shows clear manual fix command (chmod +x <path>) if auto-repair fails
• 🔧 Postinstall Binary Download: Fixed binary not being downloaded during npm install
  • Postinstall script now explicitly calls ensureCloudflared() instead of relying on module-level guard that didn't trigger during install
  • Errors during postinstall are now logged as warnings instead of being silently swallowed
  • Users are informed the binary will be downloaded on first run if postinstall fails

Improved

• 🧹 Orphaned Tunnel Cleanup: Spawn failures now trigger automatic tunnel cleanup
  • Previously, if cloudflared failed to start after tunnel creation, the tunnel was left orphaned on the backend
  • Now calls TunnelOrchestrator.cleanup() on fatal spawn errors to delete the tunnel
• 💡 Linux/macOS Error Guidance: Added EACCES-specific troubleshooting tips
  • Detects permission denied errors on Unix systems
  • Provides actionable steps: chmod +x command and reinstall instructions
  • Matches the existing Windows-specific error guidance

Technical Details

• Defense-in-depth: Permission issues are caught at 4 layers:
  1. Postinstall: downloads binary and sets chmod 755
  2. ensureCloudflared(): runs on every startup, re-applies permissions
  3. BinaryManager.validate(): checks X_OK access, auto-fixes with chmod
  4. BinaryManager.handleError(): shows troubleshooting tips + cleans up tunnel
• BinaryManager.attachHandlers(): New onFatalError callback parameter for spawn error recovery