Skip to main content

Troubleshooting

Common issues and solutions for ChemAudit installation, deployment, and operation.

Installation Issues​

Docker containers won't start​

Port already in use:

# Find what's using the port
lsof -i :8001

# Change port in docker-compose.yml or kill the process

Cannot connect to Docker daemon:

# Start Docker service
sudo systemctl start docker

# Or on macOS, launch Docker Desktop

Out of memory:

Increase Docker memory allocation:

  • Docker Desktop: Settings → Resources → Memory → 4GB+
  • Linux: Check system memory with free -h

Frontend won't load​

Blank page or React errors:

# Clear and rebuild
cd frontend
rm -rf node_modules dist
npm install
npm run dev

Cannot connect to API:

Verify backend is running:

curl http://localhost:8001/api/v1/health

Check CORS settings in .env:

CORS_ORIGINS_STR=http://localhost:3002,http://127.0.0.1:3002

Validation Errors​

Invalid SMILES​

Unclosed rings:

InvalidValidFix
C1CCC1C1CCCC1Close all rings

Too many bonds:

InvalidValidFix
CC(C)(C)(C)CCC(C)(C)CCheck valence

Invalid aromatic:

InvalidValidFix
c1cccc1c1ccccc1Benzene needs 6 carbons

Kekulization failed​

Check aromatic ring follows Hückel's rule (4n+2 electrons).

Batch Processing Issues​

File too large​

Check deployment limits:

curl http://localhost:8001/api/v1/config

Use larger profile or split file:

# Split SDF
split -l 10000 large.sdf chunk_

# Deploy larger profile
./deploy.sh large

Progress stuck at 0%​

# Check Celery worker
docker-compose logs celery-worker

# Check Redis (set REDIS_PASSWORD in your shell to the value from .env)
docker-compose exec redis redis-cli -a "$REDIS_PASSWORD" ping

# Restart workers
docker-compose restart celery-worker

CSV column not detected​

Ensure CSV has headers and use supported column names:

  • SMILES, smiles, Smiles
  • CANONICAL_SMILES, canonical_smiles

API Errors​

HTTP 429 - Rate Limited​

You exceeded the rate limit. Solutions:

  • Wait for the number of seconds in the Retry-After header, then retry
  • Use an API key so your requests are counted separately from other clients on the same IP (the limits are the same)
  • Use batch processing for many molecules

HTTP 500 - Internal Server Error​

# Check backend logs
docker-compose logs backend

# Restart backend
docker-compose restart backend

HTTP 504 - Gateway Timeout​

Request took too long. For complex molecules, this is normal.

Performance Issues​

Slow validation​

First request cold start: Wait ~10s after startup for RDKit initialization.

Complex molecules: Expected for molecules with many rings and stereocenters.

Resource constraints:

# Check container resources
docker stats

Batch processing slow​

Scale workers:

# Use larger profile
./deploy.sh large  # 8 workers

# Or scale manually
docker-compose -f docker-compose.prod.yml up -d --scale celery-worker=8

Check worker utilization:

docker-compose exec celery-worker celery -A app.celery_app inspect active

Docker Issues​

Images won't build​

# Clear Docker cache
docker system prune -a
docker-compose build --no-cache

Container keeps restarting​

# Check logs
docker-compose logs --tail=50 backend

# Recreate containers
docker-compose down
docker-compose up -d

Database connection refused​

# Check PostgreSQL health
docker-compose exec postgres pg_isready -U chemaudit

# Verify connection string in .env
DATABASE_URL=postgresql+asyncpg://chemaudit:password@postgres:5432/chemaudit

Use postgres (service name) not localhost inside Docker.

IUPAC Conversion Issues​

OPSIN not available​

OPSIN requires Java JRE. In Docker, this is pre-installed. For local development:

# Check Java is installed
java -version

# Set OPSIN JAR path in .env
OPSIN_JAR_PATH=/path/to/opsin.jar

Name conversion fails​

  • Systematic names: Should work via OPSIN (offline)
  • Common/trade names: Require PubChem API (internet needed)
  • Obscure names: May not be in PubChem — try the systematic IUPAC name instead

Bookmark & History Issues​

Bookmarks not appearing​

Bookmarks are session-scoped. If your session cookie expired (30 days), previous bookmarks are no longer accessible.

History shows no entries​

History entries are created automatically during validation. Check that your session cookie is active by looking for the chemaudit_sid cookie in your browser.

Webhook Issues​

Webhook not firing​

# Verify environment variables are set
echo $WEBHOOK_URL
echo $WEBHOOK_SECRET

# Test webhook endpoint manually
curl -X POST $WEBHOOK_URL -H "Content-Type: application/json" -d '{"test": true}'

Webhook signature mismatch​

Ensure WEBHOOK_SECRET matches on both ChemAudit and your receiving server. The signature is HMAC-SHA256 of the raw request body.

Getting Help​

Collect Debug Information​

# System info
uname -a
docker --version
docker-compose --version

# Container status
docker-compose ps

# Recent logs
docker-compose logs --tail=100 > debug_logs.txt

# Resource usage
docker stats --no-stream

Report Issues​

Open a GitHub Issue with:

  • Description of the problem
  • Steps to reproduce
  • Debug information from above
  • Screenshots (if applicable)

Next Steps​