Troubleshooting

Cannot Sign In to the Admin Panel

Symptoms

• Clicking the Magic Link shows “Unauthorized” or “Token Invalid”
• Page is blank or fails to load

Steps

1. Check link integrity

   ❌ https://xxx-00.realvco.com/?token=abc... (possibly truncated)
   ✅ https://xxx-00.realvco.com/?token=eyJhbG... (full long URL)

   • Make sure you copied the complete URL
   • Check for a “view full URL” option in the email

2. Check if the token expired

   • Magic Links expire after 24 hours
   • They also invalidate after first use
   • Fix: copy the URL fresh from the email, or contact support to resend

3. Clear browser cache

   • Ctrl+Shift+R (Windows) or Cmd+Shift+R (Mac) to hard-refresh
   • Or open an incognito window

4. Check network connectivity

   • Confirm other sites work
   • Try a different network (e.g., phone hotspot)

---

AI Companion Is Unresponsive

Symptoms

• Messages receive no reply
• “Typing…” indicator stays forever

Steps

1. Check container state

   • Open the Admin Panel
   • Verify the companion’s status is “Running”
   • If not, click “Start”

2. Check Gateway connectivity

   • In the Admin Panel, look at Gateway status
   • If “Disconnected”, it may be a network hiccup
   • Fix: wait for auto-reconnect, or restart the container

3. Check model configuration

   • Verify the container has a valid AI model
   • Confirm the API key is still active

4. Inspect logs

   • Click the container’s “Logs” button
   • Look for red error lines

---

Messaging Connection Failed

Symptoms

• QR scan does nothing
• “Pairing failed” or “Token Invalid”

By Platform

Telegram

1. Verify Bot Token

   • Make sure you copied the full token from @BotFather
   • Format: 123456789:ABCdefGHIjklMNOpqrSTUvwxyz

2. Confirm the bot wasn’t deleted

   • Search for your bot on Telegram
   • If it’s gone, recreate it

3. Check the webhook

   • Verify the Telegram config in the Admin Panel
   • Try resetting the webhook

WhatsApp

1. Use the correct path

   • WhatsApp Business API requires application
   • Personal WhatsApp cannot be directly integrated

2. Check phone number

   • Confirm the format includes the country code
   • Example: +14155551234

LINE

1. Verify Channel Secret and Token

   • Copy from LINE Developers Console
   • Distinguish Channel Secret (shorter) from Channel Access Token (longer)

2. Confirm the Webhook URL

   • Set the correct Webhook URL in LINE Console
   • Format: https://xxx-1.realvco.com/messaging/line/webhook

---

Slow or Sluggish

Symptoms

• Admin Panel loads slowly
• AI replies take forever (> 30 seconds)
• Container actions (Start / Stop) lag

Steps

1. Check resource usage

   • See the Admin Panel System Bar resource charts
   • Watch CPU, memory, disk

2. When resources are maxed

   Memory > 90%:

   • Restart the container to free memory
   • Reduce concurrent tasks

   CPU pegged at 100%:

   • Look for rogue processes (possible miner)
   • Use container logs to find the high-CPU process

   Disk > 90%:

   • Run “Docker Prune” to clear unused images
   • Delete unnecessary files

3. Check network latency

   • ping xxx-00.realvco.com to test
   • High latency could be a CDN node issue

---

Container Won’t Start

Symptoms

• Clicking “Start” but status stays “Stopped”
• Or stuck on “Starting”

Steps

1. Inspect logs

   • Click “Logs” to read startup errors
   • Common cases:
     • port already in use → port collision, reboot the whole system
     • out of memory → low memory, free up resources and retry

2. Check disk space

   • If the disk is full, the container cannot write
   • Run Docker Prune to reclaim space

3. Reboot the server

   • MAIN tab → “Reboot Server”
   • Wait 1 to 2 minutes, then retry

---

Missing or Corrupted Data

Symptoms

• The AI seems to have “forgotten” configuration
• Conversation history missing
• Files gone

Common Causes

1. Container was rebuilt

   • Rebuilt containers lose their data
   • Prevention: regular Export Data backups

2. Disk was full

   • The system may have auto-cleaned old data
   • Fix: free space, restore from backup

3. Database corruption

   • Rare, but possible
   • Fix: restore from backup or reconfigure

---

Cannot Reach a Specific Site / API

Symptoms

• The AI says it cannot reach a URL
• API calls fail

Possible Causes

1. DNS issue

   • Try nslookup example.com in Host Terminal
   • Failures suggest DNS config

2. Firewall block

   • The target may be blocking Cloudflare IPs
   • Try a different connection path

3. SSL cert issue

   • Older clients may reject newer TLS
   • Update the relevant package or client

---

Pre-Support Checklist

Before contacting support, confirm:

• Exact error message — full text or screenshot
• Time of occurrence — when did it start?
• Scope — everything broken, or a single feature?
• Things already tried — what did you test?
• Recent changes — any config changes before the issue?

Collecting Useful Logs

1. Container logs:

   # In the Admin Panel Terminal
   docker logs oc-1 --tail 100

2. System logs:

   # Most recent system messages
   journalctl -n 100

3. Network checks:

   # Connectivity probe
   ping -c 4 google.com
   curl -I https://api.telegram.org

---

Still stuck? Share the above with support and we’ll dive in.