Skip to content

Troubleshooting

Common issues encountered with hemlock-lab and their solutions.

Container Won't Start

Symptom: docker compose ps shows a container as exited or restarting.

Cause: Dependency not ready, port conflict, or image build failure.

Solution:

# Check logs for the failing container
docker compose logs langchain-rag --tail 50

# Restart just that container
docker compose restart langchain-rag

# If the image needs rebuilding
docker compose up -d --build langchain-rag

Ollama Connection Refused

Symptom:

ConnectionError: HTTPConnectionPool(host='host.docker.internal', port=11434)

Cause: Ollama isn't running on the host, or the host.docker.internal DNS isn't resolving (Linux without the extra_hosts mapping).

Solution:

# Verify Ollama is running on the host
curl -sf http://localhost:11434/api/tags

# If not running, start it
ollama serve &

# On Linux, ensure docker-compose.yml has:
# extra_hosts:
#   - "host.docker.internal:host-gateway"

ChromaDB Collection Already Exists

Symptom:

chromadb.errors.UniqueConstraintError: Collection noise-corpus already exists

Cause: Running ingestion again without resetting ChromaDB first.

Solution:

# Option 1: Full reset
docker compose down -v && docker compose up -d

# Option 2: Delete the collection manually
curl -X DELETE http://localhost:8000/api/v1/collections/noise-corpus

Pipeline Import Errors

Symptom:

ModuleNotFoundError: No module named 'langchain_community'

Cause: Image was built with stale dependencies, or requirements changed.

Solution:

# Rebuild the image with no cache
docker compose build --no-cache langchain-rag

# Restart
docker compose up -d langchain-rag

Ollama Model Pull Timeout

Symptom:

pulling manifest... Error: read tcp: connection reset

Cause: Network issue during model download.

Solution:

# Retry the pull on the host
ollama pull smollm2:135m
ollama pull nomic-embed-text

# Verify
ollama list

Port Already in Use

Symptom:

Error: listen tcp4 0.0.0.0:8100: bind: address already in use

Cause: Another process or previous container is using the port.

Solution:

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

# Force remove any orphan containers
docker compose down --remove-orphans
docker compose up -d

Disk Space Issues

Symptom: Containers failing with write errors, builds failing.

Cause: Docker images and volumes consuming disk space.

Solution:

# Check Docker disk usage
docker system df

# Remove unused images and build cache
docker system prune -f

# Nuclear option: remove everything not currently running
docker system prune -a --volumes -f

Health Check Failing

Symptom: docker compose ps shows a container as unhealthy.

Cause: The service inside the container hasn't started yet, or it crashed.

Solution:

# Check health check logs
docker inspect --format='{{json .State.Health}}' hemlock-lab-langchain-rag-1 | jq

# Check container logs
docker compose logs langchain-rag --tail 20

# Restart
docker compose restart langchain-rag

Getting Help

If you encounter an issue not listed here:

  1. Check container logs: docker compose logs <service> --tail 100
  2. Run health checks: curl -sf http://localhost:<port>/health
  3. Check the GitHub Issues for known problems

Next Steps