General Troubleshooting

​

Checking System Health First

# Check all containers are running
xr status

# Check recent logs for errors
xr logs

​

Containers

​

A container keeps restarting

# See which container is restarting
docker ps -a

# Check its logs for the error
docker logs xr-ui --tail 50
docker logs xr-watcher --tail 50
docker logs xr-api --tail 50
docker logs ollama --tail 50

• Port conflict: Another process is using port 8501 or 8510. Find it with sudo ss -tlnp | grep 8501 and stop it.
• Volume mount error: The app/, data/, or storage/ directories don’t exist or have wrong permissions. Check with ls -la /opt/xr/.
• Out of memory: The server is running out of RAM. Check with free -h. Consider closing other applications or upgrading RAM.

​

The UI shows “Please wait…” indefinitely

docker logs xr-ui --tail 100

​

Containers start but the site is unreachable

sudo nginx -t          # Test config for errors
sudo systemctl status nginx
sudo journalctl -u nginx --tail 50

docker ps
# xr-ui should show 0.0.0.0:8501->8501/tcp
# xr-api should show 0.0.0.0:8510->8510/tcp

​

AI Processing

​

Documents stay in “Processing” status indefinitely

# Is the watcher container running?
docker ps | grep xr-watcher

# Check watcher logs for errors
docker logs xr-watcher --tail 100

# Is Ollama responding?
docker exec ollama ollama list
# Should show qwen3.5:9b in the list

• Model not pulled: Run docker exec ollama ollama pull qwen3.5:9b
• Ollama out of VRAM: Check GPU memory with nvidia-smi — if VRAM is full, another process may be using the GPU
• Watcher crashed: Restart with docker restart xr-watcher

​

First document takes more than 10 minutes

docker exec ollama ollama run qwen3.5:9b "Ready" --keepalive -1

​

AI extracts wrong fields

1. Is the correct profile selected for this document type? (Standard Invoice for invoices, Chinese Fapiao for fapiao, etc.)
2. Are the field labels in your custom profile clear and descriptive?
3. Is the document quality sufficient — clear text, good scan resolution?

​

Confidence scores are consistently low

• Wrong extraction profile for the document type — create a custom profile that matches your specific format
• Poor document image quality — rescan at 300 DPI minimum
• Unusual document layout — add field descriptions in your profile to guide the AI

​

UI Issues

​

Chat returns empty responses

docker logs xr-ui --tail 50

​

PDF preview is broken / shows blank

docker exec xr-ui python -c "from pdf2image import convert_from_path; print('ok')"

docker exec xr-ui pip install pdf2image==1.17.0 --break-system-packages

cd /opt/xr/cloud
docker compose build ui
docker compose up -d ui

​

“Database is locked” errors

docker restart xr-watcher

​

Authentication

​

Locked out of the admin account

# Generate a new bcrypt hash for your new password
docker exec xr-ui python -c "
import bcrypt
pw = b'YOUR_NEW_PASSWORD'
print(bcrypt.hashpw(pw, bcrypt.gensalt()).decode())
"

# Update the database
docker exec xr-ui python -c "
import sqlite3
conn = sqlite3.connect('/data/xr_docs.db')
conn.execute(\"UPDATE users SET password_hash='PASTE_HASH_HERE' WHERE username='admin'\")
conn.commit()
conn.close()
print('Done')
"

​

Running the Test Suite

xr test
# Should report 80/80 passing