Back to docs
Troubleshooting
Install · Update · Chat

Fix common Termchat issues

Guidance lifted from the user guide for installation problems, updates, connectivity, chat, uploads, and accounts. Follow the steps below or jump to GitHub support.

Install guideUsage guide

Installation issues

Permission denied
chmod +x termchat

Ensure the binary is executable before moving it.

Still blocked? Check ls -l $(which termchat) for executable bits.
Command not found

Confirm Termchat is on PATH (e.g., /usr/local/bin).

Add PATH entries per the installation guide if missing.

macOS blocked app
xattr -d com.apple.quarantine /usr/local/bin/termchat

Or allow the binary in System Settings → Privacy & Security.

Wrong architecture

Run uname -m and download the matching build (AMD64 vs ARM64).

Errors like "cannot execute binary file" usually mean the architecture is incorrect.

Can't write to /usr/local/bin

Use user paths instead:

mkdir -p ~/bin
mv termchat ~/bin/
echo 'export PATH="$HOME/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

Update issues

Update notification missing
  • Requires v1.3.0 or later.
  • Notifications are silent when offline.
  • Check manually with termchat --update.
Updater fails
  • Run with sudo if Termchat is in /usr/local/bin.
  • If a release exists but you see "You're already on the latest version", re-run the install script.
  • Compare termchat --version with GitHub releases.

Connection and chat

Stuck connecting
  • Verify your internet connection and server status.
  • Close and reopen Termchat; log in again if the session expired.
  • Reconnect by leaving and rejoining the room if needed.
Messages not appearing
  • Check the status line for connection state.
  • If disconnected, Termchat auto-retries; you can also rejoin the room manually.

File upload issues

File not found
  • Confirm the file path; use absolute paths or ~ for home.
  • Ensure the file still exists and is readable.
File too large or failed
  • Uploads are limited to 10 MB.
  • Compress or split large files; retry with a smaller file to confirm connectivity.
  • Check your connection if uploads consistently fail.

Account issues

Invalid credentials

Re-enter your username/password or create a new account if you can't recover the password.

Username problems
  • "User already exists": pick a different username.
  • "Username must be at least 4 characters long": choose a longer name.
  • "Username can only contain letters and numbers": avoid spaces, symbols, or emojis.

General tips

  • Force quit with Ctrl+C if a session is stuck, then relaunch.
  • Run termchat --help for built-in shortcuts and commands.
  • Use a modern terminal (iTerm2, Alacritty, Windows Terminal) if you see strange characters or no colors.

Get more help

Open an issue on GitHub for bugs, or start a discussion for feature requests and questions.