Troubleshooting Guide

This document helps you resolve problems you may encounter while deploying and running OntiCards.

1. Deployment Issues

1.1 Docker Fails to Start

Symptoms: the containers fail to start after running docker-compose up

Steps to diagnose:

1. Check whether Docker is running properly:

   docker --version
   docker-compose --version

1. View the detailed error messages:

   docker-compose up
   # Omit the -d flag to see live logs

1. Common errors and their fixes:

1.2 Port Already in Use

Symptoms: "port is already allocated" or "Ports are not available"

Fix:

1. Check which process is using the port:

   # Windows
   netstat -ano | findstr :3000

   # Linux/Mac
   lsof -i :3000

1. Stop the program using the port, or change the port mapping in docker-compose.yml:

   services:
     frontend:
       ports:
         - "3001:3000"  # Change to another available port

1.3 Containers Keep Restarting

Symptoms: a container exits immediately after starting, or restarts repeatedly

Steps to diagnose:

1. View the container logs:

   docker-compose logs -f <service-name>

1. Common causes and fixes:

2. Access Issues

2.1 Cannot Open the Frontend Page

Symptoms: the browser reports "can't connect" when opening http://localhost:3000

Steps to diagnose:

1. Confirm whether the containers are running:

   docker-compose ps

1. View the frontend logs:

   docker-compose logs -f frontend

1. Check the port mapping:

   docker port onticards-frontend

• Containers not started → run docker-compose up -d

• Incorrect port mapping → check docker-compose.yml

• Blocked by the firewall → check the firewall settings

1. Common causes:

2.2 Backend API Requests Fail

Symptoms: the frontend page loads, but operations fail with a "request failed" error

Steps to diagnose:

1. Confirm whether the backend service is running:

   docker-compose ps backend

1. View the backend logs:

   docker-compose logs -f backend

1. Test whether the API responds:

   curl http://localhost:8000/api/health

3. Database Connection Issues

3.1 Cannot Connect to the Target Database

Symptoms: "test connection" fails when adding a data source

Steps to diagnose:

1. Check whether the target database is running

1. Confirm network connectivity:

   # Test if the port is reachable
   telnet <target-ip> <port>

   # Windows PowerShell
   Test-NetConnection -ComputerName <target-ip> -Port <port>

1. Check the firewall settings

1. Confirm the username and password are correct

1. Confirm the database allows remote connections

Common database ports:

3.2 Connection Timeout

Symptoms: "connection timeout" when testing a connection

Possible causes:

• The network is unreachable

• Blocked by the firewall

• The database has reached its maximum connection limit

• The connection limit has been hit

Fix:

• Check the network and firewall

• Ask your DBA to raise the connection limit or release idle connections

• Confirm the host address in the connection settings is correct

4. LLM Issues

4.1 LLM API Calls Fail

Symptoms: queries fail with "LLM call failed" or "API request error"

Steps to diagnose:

1. View the backend logs:

   docker-compose logs -f backend | grep -i "llm\|openai\|qwen"

1. Check the environment variables:

   # Verify the configuration is loaded correctly
   docker-compose exec backend env | grep LLM

1. Common causes and fixes:

4.2 Network Access Issues

Symptoms: overseas services such as OpenAI cannot be reached from mainland China

Fix:

1. Configure a proxy:

   # Configure the proxy in .env
   LLM_BASE_URL=http://your-proxy:7890

1. Or use a domestic model:

   LLM_PROVIDER=qwen    # Alibaba Qwen
   LLM_PROVIDER=moonshot # Moonshot AI

5. Data Card Generation Issues

5.1 Data Card Generation Is Slow

Symptoms: after adding a data source, data card generation is very slow or gets stuck

Possible causes:

• Too many tables

• Slow LLM responses

• Unstable network

Fix:

• Be patient; the first generation takes some time

• Check whether the LLM service is healthy

• Add tables in batches when there are many

5.2 Data Card Generation Fails

Symptoms: "data card generation failed"

Steps to diagnose:

1. Look for the specific error in the backend logs

1. Check whether the LLM service is healthy

1. Confirm the target database connection is working

1. Check database permissions (read access to the table structure is required)

6. Data Quality Check Issues

6.1 Quality Check Rules Fail to Execute

Symptoms: an error occurs when running a quality check

Steps to diagnose:

1. Check the execution logs for the specific error

• Syntax error in the rule SQL → review the rule configuration

• Database connection problem → confirm the data source is healthy

• Insufficient permissions → confirm SELECT permission is granted

1. Common causes:

6.2 Quality Check Results Are Empty

Symptoms: the check completes without detecting any issues

Possible causes:

• The data genuinely has no problems

• The rule is configured too loosely

• The rule conditions do not match the actual data

7. Performance Issues

7.1 The System Is Slow

Areas to investigate:

1. Check resource usage:

   docker stats

• Not enough memory → increase the Docker memory limit

• Not enough disk space → clean up the disk

• Too many concurrent requests → apply rate limiting or scale out

1. Common causes:

7.2 Query Timeout

Symptoms: queries take a long time without a response, or time out

Fix:

• Increase the query timeout setting

• Reduce the query scope (e.g. shorten the time range)

• Check database performance

8. Viewing Logs

8.1 View Logs for All Services

docker-compose logs -f

8.2 View Logs for a Specific Service

# Backend logs
docker-compose logs -f backend

# Frontend logs
docker-compose logs -f frontend

8.3 Limit the Number of Log Lines

docker-compose logs --tail=100 backend

8.4 Search for a Specific Keyword

docker-compose logs | grep -i "error"

9. Quick Diagnostic Commands

# 1. Check container status
docker-compose ps

# 2. Check resource usage
docker stats

# 3. Check port usage
netstat -ano | findstr "3000 8000"

# 4. Test network connectivity
ping <target-host>

# 5. Test port connectivity
telnet <target-host> <port>

# 6. View service logs
docker-compose logs -f

10. Getting More Help

If none of the above resolves your issue:

1. See the FAQ for common questions

1. See the user manual to learn how to use the features

1. Submit a GitHub Issue: https://github.com/stepll2026/OntiCards/issues

When submitting an Issue, please provide:

• The error log (redact any sensitive information)

• A description of the steps to reproduce

• Environment information (operating system, Docker version, etc.)

---

Last updated: August 2026