Iruka iconIrukaIruka home

Troubleshooting

App Won't Launch

"Iruka is damaged and can't be opened" — This is a Gatekeeper quarantine issue. Run the following in Terminal and try again:

xattr -cr /Applications/Iruka.app

App crashes on launch — Check Console.app for crash reports. If this is a fresh install, try deleting the preferences file and relaunching:

rm ~/Library/Preferences/com.dorienherremans.iruka.plist

Terminal Issues

Terminal shows garbled characters — Your TERM environment variable may be unset or wrong. Add this to your shell profile:

export TERM=xterm-256color

Colours look wrong — Enable 256-colour or true colour support in your shell/editor. In .zshrc or .bashrc:

export COLORTERM=truecolor

Shell doesn't load my profile — Check that your shell is set correctly in Preferences → General → Shell and that your profile file (.zshrc, .bash_profile, etc.) exists and is readable.

SSH Connection Issues

Connection refused — Verify the host, port, and that the SSH daemon (sshd) is running on the remote server.

Authentication failed (password) — Check the username and password. Some servers disable password authentication — use an SSH key instead.

Authentication failed (key) — Ensure your public key is in ~/.ssh/authorized_keys on the server and has permissions 600. Check that the key format is supported (Ed25519 and RSA 2048+ are broadly compatible).

Host key warning — If you rebuilt the server, remove the old known-hosts entry:

ssh-keygen -R hostname

Connection drops frequently — Add the following to ~/.ssh/config on your Mac:

Host *
  ServerAliveInterval 60
  ServerAliveCountMax 3

FTP / Cloud Mount Issues

"FTP mount failed or timed out" — FTP and cloud mounts need the official rclone plus a FUSE layer. See FTP & Cloud Mounts → Requirements for the full setup. The two most common causes:

  • rclone came from Homebrew. Homebrew's macOS rclone can't mount. Replace it with the official build:

    brew uninstall rclone
curl https://rclone.org/install.sh | sudo bash

  • No FUSE layer installed. Install fuse-t (no reboot or approval needed):

    brew install --cask fuse-t

Iruka warns about both in the connection dialog before you connect. When a mount does fail, the error message now includes rclone's own last lines, which usually name the exact cause.

"Could not prepare FTP credentials" — The rclone binary can't be read to verify its code signature (the installer sometimes leaves it execute-only). Make it readable:

sudo chmod 755 /usr/local/bin/rclone

FTPS certificate error — If you enabled Use TLS (FTPS) and see a certificate/verification error, the server is presenting a certificate for a different hostname (common on shared hosting). Connect without TLS, or use the exact hostname the certificate was issued for.

Sync doesn't move the terminal to the right folder (PowerShell) — Ensure PowerShell (pwsh) is selected in Preferences → Terminal → Shell and that you opened a new tab after changing the shell. Existing tabs keep the shell they started with.

PowerShell profile takes a long time to load — If the first Sync cd after opening a tab seems to be ignored, your PowerShell profile may still be loading. Wait a moment and navigate again; Sync will catch up once the shell is ready.

Sync fails for a path with brackets or special characters — Iruka uses Set-Location -LiteralPath for PowerShell tabs, which treats [, ], and other glob characters literally. If you still see errors, check that the path exists and is accessible.

Sync stops following after su, sudo -i, ssh, tmux, or a REPL — These start a nested interactive shell, which looks like a running command to Iruka, so Sync pauses ("Sync paused — terminal is busy") to avoid injecting a cd into it. Click Sync (or Re-enable in the banner) to resume. See Terminal → When Sync pauses automatically. (For su - specifically, following is limited anyway — it starts in the other user's home and may lack permission for your current folder.)

License Issues

See License & Activation for the full guide. Key points:

  • Your key is in the LemonSqueezy email with subject "Your Iruka Personal (X year updates) receipt"
  • Paste the key with no extra spaces
  • Activation requires an internet connection the first time

Updates Not Working

Update check fails — Make sure macOS is not blocking outbound connections for Iruka in System Settings → Network → Firewall.

Stuck on old version — Quit Iruka fully (⌘ Q), relaunch, and try Iruka → Check for Updates… again.

Still Stuck?

GitHub Issues is the best place for support, bug reports, and feature requests — the developer tracks and responds there:

👉 github.com/dorienh/iruka-releases/issues

When filing an issue, please include:

  • The version of Iruka (Iruka → About Iruka)
  • Your macOS version
  • A description of the issue and steps to reproduce it
  • Any relevant crash logs from Console.app

For general questions or to share ideas, use Discussions.

Prefer email? Reach the developer at support@dorienherremans.com.