# Common Issues & Solutions This section covers common issues you may encounter while using Genie and how to resolve them. Most problems can be resolved quickly by following the steps outlined here. If your issue is not covered, you can always ask the AI assistant inside Genie for real-time help. *** ## Connection Issues ### Terminal not connecting If your terminal shows a loading state or fails to connect: * Refresh the browser with a hard reload * Check your internet connection * Verify that your server is running from your settings * Try from a different network if you are behind a corporate firewall * WebSocket connections require outbound access on port 443 ### Session expired If you are logged out unexpectedly: * Log in again — your session will be restored * Sessions expire after extended periods of inactivity * Enable persistent sessions in your browser settings ### Frequent disconnections If your connection drops regularly: * Disable browser extensions that may block WebSocket connections * Test with a different network (try a mobile hotspot) * Check if a VPN is interfering with the connection *** ## Terminal Issues ### Terminal is blank or frozen * Press Enter a few times — the prompt may be hidden * Type `reset` and press Enter to restore the terminal state * Hard refresh your browser * Restart your server from settings ### Command not found If a tool you installed is not recognized: * Restart your shell session with `exec bash` * Verify the tool is installed with `which ` * Check your PATH variable with `echo $PATH` ### Copy and paste not working In terminal environments, use: * `Ctrl+Shift+C` to copy * `Ctrl+Shift+V` to paste * On Mac: `Cmd+C` and `Cmd+V` work as expected *** ## File Issues ### Upload stuck or failed * Check your disk space with `df -h` * Ensure the file is within size limits * Try uploading from the terminal using `wget` or `scp` instead ### Disk space full * Identify large files: `du -sh * | sort -hr | head -20` * Clean package caches: `sudo apt-get clean` * Remove old logs: `sudo rm -rf /var/log/*.gz` * Consider upgrading your plan for more storage *** ## Chat and Integration Issues ### Bot not responding on Telegram or Discord * Verify the bot is connected in Settings → Channels * Check your credit balance — no credits means no responses * Try sending `/start` to the bot * Disconnect and reconnect the integration ### Messages sent but no response * Wait 30 seconds — complex queries take longer * Check your credit balance * Verify server is running *** ## Server Issues ### Server won't start * Wait up to 2 minutes for startup to complete * Try a force stop followed by restart from settings * Check the status page for any ongoing issues ### Server is slow * Check resource usage with `htop` * Identify and stop resource-heavy processes * Review disk I/O and memory usage * Upgrade your plan if resources are consistently maxed *** ## Login and Authentication ### Cannot log in * Verify you are using the correct OAuth provider (Google, GitHub, Apple) * Clear your browser cache and cookies * Try logging in from an incognito window * Check your email for any account suspension notices ### 2FA codes not working * Ensure your device's time is set automatically — TOTP codes require accurate time * Use a backup code if your authenticator is unavailable * Contact support if you are locked out completely ### GitHub authentication fails on headless server When running `gh auth login` on a VPS or headless server, the device code flow may fail with errors like "Failed opening a web browser" or the one-time code shows "we couldn't find anything" on GitHub: * **Log out first** — run `gh auth logout` before attempting to log in again * **Try a different browser** — if the device code isn't working in one browser, open an incognito window or switch to a different browser entirely * **Use a Personal Access Token instead** — on headless servers, the PAT method is more reliable: 1. Go to 2. Select the `repo` scope 3. Generate the token and run: `echo "ghp_YOUR_TOKEN" | gh auth login --with-token` * **Check the code hasn't expired** — device codes expire after \~15 minutes; if you waited too long, start over * **Verify the correct account** — make sure you're entering the code while logged into the GitHub account that has access to the target repositories *** ## Telegram Bot Reconnection ### Reconnecting a Telegram bot after recreating a server If you previously linked your own Telegram bot to a Genie server and then recreated or reset that server, you don't need to create a new bot. You can reuse your existing bot token: 1. Find your existing bot token — check your saved credentials or message history with [@BotFather](https://t.me/BotFather) on Telegram (use `/mybots` to retrieve it) 2. Go to **Settings → Channels → Telegram** 3. Expand the **"Bring your own bot"** section 4. Paste your existing bot token into the input field 5. Click **Save & Connect** 6. You should see a green confirmation: "Bot token saved. You can sync it to your server from the Secrets tab." 7. Go to **Settings → Secrets** and click **Sync** to push the token to your server — the `TELEGRAM_BOT_TOKEN` secret should show as **Active** with your server name 8. Click **Reconnect** if needed Your bot will be linked to the new server with the same Telegram handle — no need to update any group chats or contacts. ### Re-pairing users after server recreation When you recreate a server, any previously authorized users will lose access to the bot. Each user will need to be re-paired and reconfigured: 1. The user sends any message to the bot on Telegram 2. They will see an "OpenClaw: access not configured" message with their **Telegram user ID** and a **Pairing code** 3. The server admin approves the pairing by running: ``` openclaw pairing approve telegram ``` 4. After approval, the admin also needs to authorize the user and update the configuration — add the user's Telegram ID to the `allowFrom` list in the Telegram channel config 5. Once both steps are complete, the user can interact with the bot again > **Note:** This applies to every user who previously had access. Each one must re-pair individually after a server is recreated. *** ## Quick Fixes Most issues can be resolved by: 1. Hard refreshing the browser 2. Restarting your server 3. Checking your credit balance 4. Waiting a few minutes for systems to stabilize If none of these resolve your issue, contact support with details about what you were doing, what happened, and any error messages you received.