#Troubleshooting

This page maps the app's real error messages to causes and fixes. For output problems (rejected files, formatting, failed chunks, subtitle warnings), see Common Issues & Fixes.

#Where To Check First

• Settings → "Local translation status" — shows whether your local engine is installed and running, with an "Open setup & downloads" shortcut. Almost every engine-related error in the app points here.
• Translations screen — per-job status badges and progress; the sidebar item shows a dot when a job is processing, errored, or ready.
• Providers screen — live status of Ollama and LM Studio, installed models, and hardware info.
• Logs — the app names backend/logs/errors.log and backend/logs/marian.log (inside the app's data folder) in its own error messages.
• Support screen — file a ticket from inside the app; enable "Include diagnostics when submitting tickets" so the report carries useful context.

#App Startup Problems

#The app does not start at all (Windows)

Cause: a missing Microsoft Visual C++ Redistributable is the most common cause on fresh machines — it is required but not bundled.

Fix:

1. Install the latest "Visual C++ Redistributable (x64)" from Microsoft.
2. Restart the machine and launch CatScribe again.
3. If it still fails, reinstall CatScribe. The startup self-test is diagnostic only — it cannot repair a corrupted install; reinstalling is the fix for damaged core files.

#"The application hit a fatal error."

Cause: an unrecoverable crash in the app runtime.

Fix: restart the app. If it recurs, reinstall the latest build, and report it via the Support screen with diagnostics enabled.

#"App database was reset"

Full message: "A corrupted local database was moved to quarantine and replaced with a fresh database."

Cause: the local database was damaged (for example by a forced shutdown). CatScribe quarantined it and started fresh — the message shows the quarantine path.

Fix: nothing to repair; the app is healthy again. If you use automatic backups (Settings → Backups), you can restore a recent backup to get your jobs and glossaries back.

#"Could Not Reach The Engine" And Friends

CatScribe's translation engine runs as a local background service. These messages describe its state — most fix themselves with a short wait.

#"The engine is still starting. Wait a few seconds and try again."

Cause: you acted within the first seconds after launch, before the backend finished booting.

Fix: wait a few seconds and retry. Large installs on slow disks take longer on cold start.

#"Could not reach the engine. Wait a few seconds if the app just started. If you use LibreTranslate, start it from Local status or Docker; Argos local translation does not need LibreTranslate."

Cause: the backend is not reachable — either it is still starting, it crashed, or (LibreTranslate only) the Docker container is not running.

Fix:

1. Wait a few seconds if the app just launched.
2. Check Settings → "Local translation status".
3. If you use LibreTranslate, start its Docker container. If you use Argos, LibreTranslate is irrelevant — do not start Docker for it.
4. If nothing responds, quit fully (Tray → Quit Application) and relaunch.

#"No backend engine is configured or running. Please start the engine or ensure it is reachable."

Cause: the backend service is down or was never set up.

Fix: same as above — Local translation status, then a full quit and relaunch. If it persists, reinstall.

#"The translation engine is busy with heavy work. History and chunks should recover shortly — wait a moment and retry." / "The request timed out while the engine was under load. This does not mean the engine is offline — try again."

Cause: a large job is consuming the engine; requests time out but the engine is alive.

Fix: wait and retry. Consider pausing the running job from the Translations screen if you need the app responsive right now.

#"The engine is running but temporarily degraded. Core features should still respond — retry or check diagnostics."

Cause: an optional component failed while core translation stayed up. You may also see the banner "Some features are temporarily unavailable" with "Optional providers failed to start. You can retry or continue with available features."

Fix: retry the failed feature; check Settings → Diagnostics; restart the app if the degraded state persists.

#"The selected translation provider is unavailable. Check Local Translation status or pick another provider."

Cause: the specific engine you chose (for example MarianMT) is not ready, even though the app is.

Fix: open Settings → "Local translation status" to finish its setup, or switch to another provider for this job.

#"The local translation engine isn't installed yet. Open Settings → Local translation status to set it up."

Cause: no local engine was ever installed — the First Launch Setup was skipped or its install failed.

Fix: follow the message. "Open setup & downloads" re-runs the engine setup.

#First-Run Download Failures

#Argos language packs

• "Could not reach the language pack download server. Check your internet connection and try again from the Models tab." — network problem; check connectivity, proxies, and firewalls, then retry.
• "Language pack installation was blocked (permission denied). Try again or change the install location in Settings." and "Access denied while installing Argos resources. Please close CatScribe and open it as Administrator, then try again." — Windows file permissions. Run the app as Administrator once for the install, or check that antivirus is not locking the app's data folder.
• "Argos Translate is still installing. Wait for it to finish, then try again from Settings." — a previous install is still running; the pack modal also shows "Waiting for Argos setup to finish (another install is in progress)…". Just wait.

Each pack is ~50–100 MB and downloads do not resume — a dropped connection means the pack restarts from zero.

#FFmpeg

• "FFmpeg download failed. Please try again or install FFmpeg manually." — the app adds: "If the download keeps failing, try disabling your antivirus temporarily or install FFmpeg manually and set the FFMPEG_PATH environment variable." FFmpeg is ~100 MB and only needed for video features.

#COMET

• "Timed out waiting for COMET to become ready." — the message itself notes "The first model load can take many minutes; retry". COMET is a ~1–2 GB download and first-time setup often takes 15–45+ minutes. Leave it running; retry once before assuming failure.

#LM Studio Shows The Wrong Status

The Providers screen and model selectors show one of three LM Studio states:

Key gotcha, quoted from the app: "Opening the LM Studio app does not start its Local Server — start it manually under the Developer tab." The default port is 1234; if you changed it, update "LM Studio Port (auto-detect)" in Settings → Integrations and click Save Settings.

#Ollama Problems

• "Ollama Not Installed" — install it manually or use the "Install Ollama Automatically" button on the Providers screen. Then, per the app: "After installation, restart your computer for Ollama to be detected."
• "Ollama Service Not Running" ("The Ollama service needs to be started to use Ai enhancements.") — start Ollama; CatScribe expects it at http://localhost:11434.
• "No models detected. Start Ollama and install a model in the Models tab." — Ollama runs but has no models; download one from the Providers screen's recommended list.
• "Ollama or LM Studio is not running. Start the service and ensure a model is loaded to use AI enhance." — shown by "Improve with AI" in the CAT editor; start either service with a loaded model.

#LibreTranslate (Docker) Problems

• "Docker is not available. Install Docker to run LibreTranslate from the app." — LibreTranslate is the only engine that needs Docker. Install Docker Desktop, or use Argos/MarianMT/NLLB instead.
• "LibreTranslate is starting. This may take 1–3 minutes on first run." — normal; the container downloads language data on first start. Wait, then check Settings → "Local translation status".

#Subtitle And Video Problems

• "Only .srt and .vtt files are supported" / "ASS import is not supported" — convert ASS/other formats to SRT or VTT first.
• "Subtitle file must be valid UTF-8 text" — re-save the file as UTF-8 (legacy encodings like cp1252 are rejected, not converted).
• "Subtitle chunk translation was incomplete. The chunk was not saved and will need to be retried." — the engine's answer could not be matched back to every cue; nothing was saved, so just retry the chunk.
• "Failed to translate this chunk." with the hint "Check Local status or Settings: your translation provider must be running. If the error persists, try another provider or re-upload the subtitle file." — provider outage; see the engine sections above.
• "No subtitle track was found." — the video has no embedded subtitles. CatScribe offers "Detect subtitles" (AI burned-in detection, an optional ~250 MB install). If detection ends with "No embedded subtitles found", follow the app's advice: place your SRT/VTT next to the video with the same base name and import the video again.
• "FFmpeg Required" — video features need FFmpeg; use the in-app "Download FFmpeg" (~100 MB).
• OCR detection errors — the app gives specific hints, including: "This looks like a known Paddle CPU (oneDNN) issue. Reinstall AI subtitle dependencies under Settings → Optional Dependencies…", "Free disk space is too low for OCR frame extraction…", "OCR models are missing or could not be downloaded. Connect to the internet once, reinstall optional dependencies, then run the self-test." (the "Run OCR self-test" button lives under Settings → Optional Dependencies → AI Subtitle Detection), and "This video is too long for beta OCR detection…" (use a shorter clip).
• "Unable to play this video in the current backend/runtime." / "HLS playback failed. Try H.264/AAC in MP4 or another file." — codec not supported by the built-in player; re-encode to H.264/AAC MP4. Playback issues do not block translation or export.

#Jobs That Fail Entirely

If a job ends with every chunk failed (reason "All chunks failed"), the provider was down for the whole run. Fix the engine (sections above), then use "Retry All" or "Retry Failed" on the job in the Translations screen — completed work is never thrown away, and failed chunks are also retried automatically up to 3 times while the job runs.

#Still Stuck?

Open the Support screen and send a ticket (category, title, description, steps to reproduce). Turn on "Include diagnostics when submitting tickets" so logs and status come along. For quality problems rather than errors, see Reviewing Translations and Improve With AI.