Skip to content

Troubleshooting

Common User Issues

Cannot Sign In

Symptom Cause Solution
"Invalid credentials" Incorrect email or password Verify credentials / contact Admin for password reset
Blank screen Incorrect URL Verify the URL with your administrator
"Account pending" Account not yet approved Contact Admin for account approval

No Models Available

Symptom Cause Solution
"No results found" Group not granted model access Contact Admin to assign model access to your group
Empty list AI connections not configured Admin needs to configure Connections first

AI Not Responding / Slow

Symptom Cause Solution
Long wait, no response AI provider issue Try switching models / wait and retry
Red "Error" message API Key expired or invalid Admin should verify API Key in Connections
401 error with Claude Authentication header incompatible Use OpenRouter instead of direct Anthropic API connection

Knowledge Base Not Working

Symptom Cause Solution
AI doesn't reference documents Knowledge Base not selected Use # to select a Knowledge Base before asking
"Processing" stuck File too large Split into smaller files / try re-uploading
Inaccurate answers Documents don't cover the question Add more relevant documents

Administrator Issues

System Completely Inaccessible

# Check if containers are running
docker compose ps

# Check logs
docker compose logs --tail=50 open-webui

# Restart the system
docker compose restart

Database Connection Failed

# Check PostgreSQL logs
docker compose logs postgres

# Test connection
docker exec app-postgres pg_isready

Postgres + Docker Bridge Issue

If the system returns 502 after a server reboot, PostgreSQL may have started before the Docker bridge network was created. Restart PostgreSQL first, then the application container: 

sudo systemctl restart postgresql
sudo docker restart mea-open-webui

Storage Full

# Check disk usage
docker system df
df -h

# Clean Docker cache
docker system prune -a

Connection Index Drift

Warning

AI connections are stored as ordered arrays. Do not delete a connection from the beginning or middle of the list -- this causes the remaining connections' configurations to shift incorrectly. Instead, use enable: false to disable a connection without removing it. Adding or removing connections at the end of the list is safe.