GTEdgeAI/gt-ai-os-community
3
0
Fork 0
Code Issues Packages Releases Wiki Activity

Add Troubleshooting

Daniel
2026-01-10 03:27:38 +00:00
parent ae61f7890d
commit d1f1294234
1 changed files with 355 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

355
Troubleshooting.md Normal file

@@ -0,0 +1,355 @@
# Troubleshooting
Having problems? Find your issue below and follow the steps.
## Table of Contents
- ["I see 'docker: command not found'"](#i-see-docker-command-not-found)
- ["I see 'permission denied' when running docker"](#i-see-permission-denied-when-running-docker)
- ["I see 'port already in use'"](#i-see-port-already-in-use)
- ["The page won't load in my browser"](#the-page-wont-load-in-my-browser)
- ["Services show 'unhealthy' or 'starting'"](#services-show-unhealthy-or-starting)
- ["I forgot the login password"](#i-forgot-the-login-password)
- ["I can't log in after deleting the default admin account"](#i-cant-log-in-after-deleting-the-default-admin-account)
- ["API key test fails"](#api-key-test-fails)
- ["Models not appearing in the list"](#models-not-appearing-in-the-list)
- ["Agent doesn't use my dataset"](#agent-doesnt-use-my-dataset)
- ["Document stuck in 'Processing'"](#document-stuck-in-processing)
- ["I'm locked out due to Two-Factor Authentication (TFA)"](#im-locked-out-due-to-two-factor-authentication-tfa)
- ["My AI agent doesn't respond"](#my-ai-agent-doesnt-respond)
- ["How do I see what's happening behind the scenes?"](#how-do-i-see-whats-happening-behind-the-scenes)
- ["I want to start completely fresh (delete everything)"](#i-want-to-start-completely-fresh-delete-everything)
- ["Nothing above helped - I need more support"](#nothing-above-helped---i-need-more-support)
---
## "I see 'docker: command not found'"
**What this means:** Docker isn't installed on your computer.
**How to fix it:**
1. Go back to the [Installation section in the README](https://github.com/GT-Edge-AI-Internal/gt-ai-os-community#installation)
2. Follow the steps for your computer type to install Docker Desktop
3. Make sure Docker is running before trying again
---
## "I see 'permission denied' when running docker"
**What this means:** Your computer user account doesn't have permission to use Docker.
**How to fix it (Ubuntu/Linux only):**
1. Open Terminal
2. Copy and paste this command, then press Enter:
```bash
sudo usermod -aG docker $USER
```
3. Type your password when asked (you won't see characters as you type - that's normal)
4. **Important:** You must log out of your computer completely, then log back in
5. Try your command again
---
## "I see 'port already in use'"
**What this means:** Another program on your computer is using the same connection port that GT AI OS needs.
**How to fix it:**
1. Open Terminal
2. Go to your GT AI OS folder:
```bash
cd ~/Desktop/gt-ai-os-community
```
(Or wherever you installed it)
3. Stop everything:
```bash
docker compose down
```
4. Wait 10 seconds, then start again:
```bash
docker compose up -d
```
**Still not working?** Restart your computer and try again.
---
## "The page won't load in my browser"
**What this means:** Either Docker isn't running, or the services haven't started yet.
**How to fix it:**
**Step 1: Check if Docker is running**
- **Ubuntu/DGX:** Open Terminal and type:
```bash
docker ps
```
- If you see a list of containers, Docker is running
- If you see an error, start Docker with: `sudo systemctl start docker`
- **macOS:** Look at the top-right of your screen (menu bar). Do you see a whale icon?
- If yes, Docker is running
- If no, open the **Docker** app from your Applications folder
**Step 2: Wait for services to start**
After starting GT AI OS, wait 2-3 minutes for everything to load. The first time takes longer.
**Step 3: Try a different browser**
If one browser doesn't work, try another (Chrome, Firefox, Safari).
**Step 4: Check if services are running**
Open Terminal and type:
```bash
docker ps
```
You should see about 10 containers listed. If you see fewer, or none, run:
```bash
cd ~/Desktop/gt-ai-os-community
docker compose up -d
```
---
## "Services show 'unhealthy' or 'starting'"
**What this means:** The services are still loading. This is normal!
**How to fix it:**
1. Wait 2-3 minutes
2. Refresh your browser page
3. If still unhealthy after 5 minutes, restart everything:
```bash
cd ~/Desktop/gt-ai-os-community
docker compose down
docker compose up -d
```
---
## "I forgot the login password"
**Default login credentials:**
- **Email:** `gtadmin@test.com`
- **Password:** `Test@123`
These work for both the Control Panel (http://localhost:3001) and Tenant App (http://localhost:3002).
**If you deleted the default account:** You'll need to reset the database. See "I want to start completely fresh" below.
---
## "I can't log in after deleting the default admin account"
**What this means:** You deleted `gtadmin@test.com` before verifying your new account works.
**How to fix it:**
1. Open Terminal
2. Go to your GT AI OS folder:
```bash
cd ~/gt-ai-os-community # Ubuntu/DGX
cd ~/Desktop/gt-ai-os-community # macOS
```
3. Reset the database:
```bash
docker compose down -v
docker compose up -d
```
4. Wait 2-3 minutes for services to start
5. Log in with the default credentials: `gtadmin@test.com` / `Test@123`
6. **This time:** Verify your new account works BEFORE deleting the default one
---
## "API key test fails"
**For NVIDIA API keys:**
- Make sure you copied the complete key (some are longer than expected)
- Verify your account is active at https://build.nvidia.com/
- Check that the key hasn't expired
**For Groq API keys:**
- Make sure your key starts with `gsk_`
- Check that your Groq account is active at https://console.groq.com/
- Verify the key isn't deactivated in your Groq dashboard
**General tips:**
- Don't include extra spaces before or after the key
- Try generating a new key if the current one doesn't work
---
## "Models not appearing in the list"
**What this means:** The Models page is empty or missing expected models.
**How to fix it:**
1. **Check that you have an API key configured:**
- Go to Control Panel → API Keys
- You should see at least one key (NVIDIA or Groq)
- If no keys exist, add one first (see [Control Panel Guide](Control-Panel-Guide))
2. **Match providers:**
- NVIDIA models require an NVIDIA API key
- Groq models require a Groq API key
3. **Try refreshing:**
- Press F5 or Cmd+R to refresh the page
- Wait 10 seconds and check again
4. **Restart the backend:**
```bash
docker compose restart control-panel-backend
```
5. **If still empty, reset the database:**
- Models are loaded automatically during installation
- If missing, you may need to reinstall (see "I want to start completely fresh" below)
---
## "Agent doesn't use my dataset"
**What this means:** You connected a dataset to an agent, but it doesn't seem to use the documents.
**How to fix it:**
1. **Check document processing status:**
- Go to Tenant App → Datasets
- Click on your dataset
- All documents should show **Completed** status
- If any show **Processing** or **Failed**, wait or re-upload
2. **Verify the dataset is connected:**
- Go to Tenant App → Agents
- Edit your agent
- Check the **Datasets** section - your dataset should be selected
- Save if you made changes
3. **Ask about your documents:**
- Try asking a specific question about content in your documents
- Example: "What does my document say about [specific topic]?"
---
## "Document stuck in 'Processing'"
**What this means:** A document upload hasn't completed processing.
**How to fix it:**
1. **Wait longer:** Large documents (especially PDFs) can take several minutes
2. **Check the file type:** Supported formats are PDF, DOCX, TXT, MD, JSON, CSV
3. **Check file size:** Very large files may timeout
4. **Try re-uploading:**
- Delete the stuck document
- Upload again
5. **Check if embeddings service is running:**
```bash
docker ps | grep vllm-embeddings
```
- If not running, restart: `docker compose restart vllm-embeddings`
---
## "I'm locked out due to Two-Factor Authentication (TFA)"
**What this means:** You enabled TFA but lost access to your authenticator app.
**How to fix it:**
You'll need to reset the database (this deletes all data):
1. Follow the steps in "I want to start completely fresh" below
2. After reset, log in with default credentials
3. Set up your new account and enable TFA again
---
## "My AI agent doesn't respond"
**What this means:** The AI model might not be connected or configured correctly.
**How to fix it:**
1. **Check if you have a model configured:**
- Open Control Panel: http://localhost:3001
- Go to **Models** in the left sidebar
- You should see at least one model listed
- If empty, you need to [set up Ollama](Ollama-Setup) or add an API-based model
2. **Check if the model is assigned to your tenant:**
- In Control Panel, go to **Tenant Access**
- Make sure your model is assigned to a tenant
3. **If using Ollama, check it's running:**
```bash
ollama list
```
- If you see "command not found", [install Ollama first](Ollama-Setup)
- If you see your models listed, Ollama is working
---
## "How do I see what's happening behind the scenes?"
If something isn't working and you want to see the error messages:
1. Open Terminal
2. Go to your GT AI OS folder:
```bash
cd ~/Desktop/gt-ai-os-community
```
3. View the logs:
```bash
docker compose logs -f
```
4. To stop viewing logs, press `Ctrl+C` (hold Control and press C)
**Tip:** To see logs for just one service:
```bash
docker compose logs -f tenant-backend
```
---
## "I want to start completely fresh (delete everything)"
**Warning:** This will delete ALL your data, including users, agents, and conversations.
1. Open Terminal
2. Go to your GT AI OS folder:
```bash
cd ~/Desktop/gt-ai-os-community
```
3. Stop and remove everything:
```bash
docker compose down -v
```
4. Run the installer again:
- **Ubuntu:** `./installers/install-gt2-ubuntu.sh`
- **DGX:** `sudo ./installers/install-gt2-dgx.sh`
- **macOS:** `./installers/install-gt2-mac.sh`
---
## "Nothing above helped - I need more support"
1. **Check GitHub Issues:** Someone might have had the same problem:
https://github.com/GT-Edge-AI-Internal/gt-ai-os-community/issues
2. **Open a new issue:** Describe your problem and include:
- What you were trying to do
- What error message you saw
- What computer you're using (Mac, Ubuntu, DGX)
- The output of `docker compose logs` (last 50 lines)