LibreTranslate Docker Crashes: How I Fixed 5 Common Errors

I set up LibreTranslate on my homelab to keep translation work private. Seemed straightforward: spin up the Docker container, hit the REST API, done. Instead I spent an evening troubleshooting container crashes, stuck downloads, and mysterious out-of-memory kills. This is what I actually fixed.

The Setup That Kept Failing

Standard Docker Compose file, nothing fancy. I wanted to translate documents locally without sending them to Google or Microsoft. The official docs say it works. It did—after I stopped making five specific mistakes.

The errors weren’t always obvious. Some showed up in logs. Some just hung. One made the container exit silently, which is its own kind of annoying.

Error 1: Out of Memory on Model Load

First run. Container started, logs looked good for about 12 seconds, then gone. No error message, just exit code 137 (OOMKilled).

The problem: LibreTranslate downloads translation models on first run. Each model is 300–600 MB. I had three language pairs configured. My container memory limit was 512 MB. Bad math.

I checked docker inspect libretranslate | grep Memory and confirmed: 512 MB allocated. The container needed at least 1.5 GB to download and load models without getting killed mid-process.

Fix: Updated the Compose file.

version: '3.8'
services:
  libretranslate:
    image: libretranslate/libretranslate:latest
    ports:
      - "5000:5000"
    environment:
      - LT_LOAD_ONLY=en,es,fr,de
    deploy:
      resources:
        limits:
          memory: 2G
        reservations:
          memory: 1G

The LT_LOAD_ONLY variable is critical. Without it, LibreTranslate tries to preload all 30+ languages at startup. I only needed English, Spanish, French, and German. Specifying them cut startup from five minutes to 45 seconds and dropped memory from 2.2 GB to 1.1 GB steady-state.

Error 2: Model Download Timeout

After fixing memory, the container stayed alive but hung on startup. Logs said “Downloading model for en_de” and then nothing for ten minutes before the health check timed out.

Model downloads come from Hugging Face. My connection is fine, but something in the container’s network setup was slow. Could be DNS, could be the bridge interface. I added explicit timeouts and redirected model downloads to a persistent volume so they don’t re-download on every container restart.

volumes:
  - libretranslate_models:/home/user/.local/share/argostranslate/packages

environment:
  - LT_UPDATE_MODELS=false
  - LT_LOAD_ONLY=en,es,fr,de
  - HF_HUB_OFFLINE=false

The key is LT_UPDATE_MODELS=false on subsequent runs. First boot, it downloads. After that, it uses what’s in the volume. I also added a pre-pull step in my deployment script to download models before the container starts, so the app is responsive from boot.

Error 3: “Cannot assign requested address” on Port Binding

Container ran fine in the background, but I couldn’t connect to it from my Docker host. Logs showed the app listening on 0.0.0.0:5000 inside the container, but curl to localhost:5000 timed out. Tried 127.0.0.1:5000, same thing.

I’d been using ports: "5000:5000" without specifying the host interface. On my setup, Docker was binding only to the Docker network, not the host bridge. Running netstat -tlnp | grep 5000 on the host showed nothing listening.

This was operator error. The container network was isolated by design. I fixed it by being explicit about the binding:

ports:
  - "127.0.0.1:5000:5000"

If you need the API available on other machines in your network, use 0.0.0.0:5000:5000 instead. That binds to all host interfaces. I use the localhost binding and reverse-proxy through Caddy when I need external access.

Error 4: GPU Binding Fails When No GPU Present

I tried to add GPU support for faster translation since I have a spare RTX 3060. The Compose file specified runtime: nvidia and deploy.resources.reservations.devices: gpu. Container wouldn’t start. Error: “could not select device driver with capabilities gpu.”

The nvidia-docker runtime wasn’t installed. I had Docker, but not nvidia-docker. That’s two separate packages. Also, even if nvidia-docker was installed, the CUDA version in the container image didn’t match my driver version (12.2 in the image, 11.8 on my host).

I made two choices. First, I skipped GPU for now—it adds complexity and LibreTranslate’s CPU performance is adequate for my use. If I revisit it, I’d use the official libretranslate/libretranslate:latest-gpu image, which pins compatible CUDA versions. But I’d have to rebuild the whole Docker runtime setup, which isn’t worth it for translation speeds.

For reference, CPU inference on a modern Xeon takes about 2–3 seconds per sentence. That’s acceptable for my workflow. GPU would cut it to maybe 0.5 seconds, but I’m not translating documents fast enough to notice.

Error 5: “502 Bad Gateway” After Long Requests

Container ran, port bound correctly, but hitting the translate endpoint with a long document returned 502 Bad Gateway. Smaller requests worked fine. The API itself wasn’t timing out; the reverse proxy (Caddy, in my case) was.

Long translation requests can take 20+ seconds. Caddy’s default proxy timeout is 30 seconds, but it can vary depending on configuration. More importantly, the LibreTranslate app can also hang if you send a request with poorly encoded Unicode or a language pair it’s not configured to handle.

I checked both sides. First, confirmed LibreTranslate was actually responding by making a direct call inside the container:

docker exec libretranslate curl -X POST http://localhost:5000/translate 
  -H "Content-Type: application/json" 
  -d '{"q":"Hello world","source":"en","target":"es"}' 
  --max-time 60

It returned correctly. So the problem was upstream. I increased Caddy’s timeout for the `/translate` path:

translate.local {
  reverse_proxy localhost:5000 {
    timeout 60s
    policy least_conn
  }
}

I also added explicit language validation on the request side. Now I check against the list of loaded models before sending to the API, which catches misconfigurations early.

Lessons From This Mess

LibreTranslate works well once configured correctly. The main pain points are resource allocation and persistence. Give it enough memory, use LT_LOAD_ONLY to reduce startup time, mount a volume for models, and be explicit about network bindings.

I should have read the GitHub issues page before starting. At least three of these errors were documented. The official docs are sparse on production gotchas. That said, the software itself is solid. The API is predictable, the model quality is reasonable for a self-hosted option, and once running, it’s stable.

My current config has been up for six weeks without a restart. Translation requests average 2.1 seconds. I’m using it to translate support emails and the occasional document. No subscription. No data leaving the house. That’s the real win.

FAQ

How much RAM does LibreTranslate need?

At minimum 1.5 GB to download and load models on startup, plus at least 512 MB for the running app. I’d allocate 2 GB in production. Using LT_LOAD_ONLY to limit loaded languages can cut this in half.

Can LibreTranslate run on a Raspberry Pi?

Technically yes, but slowly. Translation would take 30+ seconds per sentence on a Pi 4. Most people use it on x86 hardware or a small NAS. If you have a Pi with 4+ GB RAM and a fast CPU, it’s doable for occasional low-volume translation.

What languages does LibreTranslate support?

Over 30 languages including English, Spanish, French, German, Chinese, Japanese, Russian, and Arabic. The full list is on the GitHub repo. You can load all of them or specify only the ones you need with LT_LOAD_ONLY.

Is LibreTranslate good enough to replace Google Translate?

For most use cases, yes. Quality is slightly behind Google for idiomatic translation, but it’s more than adequate for documents, emails, and support tickets. The tradeoff is speed and privacy for perfection.

Does LibreTranslate need internet access?

Only on first run to download models from Hugging Face. After that, it’s fully offline. Set LT_UPDATE_MODELS=false to skip update checks and run completely air-gapped.

Explore LibreTranslate in our AI Homelab Toolkit.