Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.
ChatGPT

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 <tool-name>

  • 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 https://github.com/settings/tokens/new

    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 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:

  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.

PreviousAdvanced UsageNextQuick Reference Guide

Last updated