GTEdgeAI/gt-ai-os-community
3
0
Fork 0
Code Issues Packages Releases Wiki Activity
Page: Troubleshooting
Pages
Cloudflare Tunnel Setup Control Panel Guide Home How to build GT AI OS Agents Installation Ollama Setup Projects for NVIDIA NIMs and Nemotron using Local Ollama Tenant App Guide Troubleshooting Updating
Clone
1
Troubleshooting
daniel edited this page 2026-01-10 03:27:38 +00:00
Table of Contents

Troubleshooting

Having problems? Find your issue below and follow the steps.

Table of Contents

"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
  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: 
    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: 
    cd ~/Desktop/gt-ai-os-community
    (Or wherever you installed it)
  3. Stop everything: 
    docker compose down
  4. Wait 10 seconds, then start again: 
    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: 
    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:

docker ps

You should see about 10 containers listed. If you see fewer, or none, run:

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: 
    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: 
    cd ~/gt-ai-os-community          # Ubuntu/DGX
cd ~/Desktop/gt-ai-os-community  # macOS
  3. Reset the database: 
    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)

  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:

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

    ollama list
    • If you see "command not found", install Ollama first
    • 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: 
    cd ~/Desktop/gt-ai-os-community
  3. View the logs: 
    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:

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: 
    cd ~/Desktop/gt-ai-os-community
  3. Stop and remove everything: 
    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)