Troubleshooting

Common issues and solutions when working with DB-GPT.

First 60 seconds

Run these first:

curl http://localhost:5670/api/health
dbgpt model list
docker logs dbgpt -f

If you are not using Docker, check the same terminal where you started the webserver.

Common quick fixes

• Server will not start
  • Re-run uv sync with the right extras
  • See Installation Issues
• Web UI is blank
  • Wait for startup to finish
  • Confirm the server is reachable on http://localhost:5670
• Model not found / auth error
  • Re-check the TOML config and provider name
  • See Model Issues
• Port 5670 is already in use
  • Find the conflicting process with lsof -i :5670
• Out of memory
  • Use a smaller local model or switch to an API proxy model

More specific guides

• Installation Issues
• Model Issues
• Environment Variables

Logs

# Source code deployment
# Logs are printed to stdout by default

# Docker deployment
docker logs dbgpt -f

# Docker Compose deployment
docker logs db-gpt-webserver-1 -f

Getting help

If the troubleshooting guides don't resolve your issue:

1. Search existing issues: GitHub Issues
2. Ask the community: GitHub Discussions
3. Join Slack: DB-GPT Slack
4. Check FAQ: Installation FAQ · LLM FAQ · KBQA FAQ