Training Captioner Troubleshooting

Troubleshooting

First step for almost everything: open View ▸ Log. It shows the exact llama-server command line, the server's own output and any per-image errors (FAILED photo.jpg: …).

Setup errors

"llama-server.exe not found: set its path in Settings."

The app could not find llama.cpp. Put it in a llama.cpp folder next to main.py, or browse to it in Settings ▸ Backend. See Installation.

"Model (.gguf) not found" / "mmproj file not found"

The paths in Settings are wrong or the file moved. Re-browse to them.

llama-server starts but immediately exits

The error dialog ends with the last lines of the server's output. Common causes:

Message in the output	Fix
failed to allocate / out of memory / cudaMalloc failed	Not enough VRAM. Lower Context per request, Concurrent requests, GPU layers, or use a smaller quant. Close other GPU programs. Use Split if the model needs more than one card
unknown model architecture	Your llama.cpp is older than the model. Update llama.cpp
mmproj / projector mismatch errors	The mmproj file belongs to a different model. Download both from the same page
address already in use / bind	Another program uses the port. Change First port in Settings
Nothing at all, exit code 0xC0000135	A DLL is missing. Unzip the cudart zip into the same llama.cpp folder
CUDA errors on a new RTX 50-series card	Use a CUDA 13 build of llama.cpp

"Timed out waiting for llama-server to load the model."

Loading took over 15 minutes. Very large models on a slow disk can; otherwise check the log for what it is stuck on.

"Add at least one endpoint URL in Settings."

You chose the External backend with an empty URL list.

Captioning problems

Empty captions / "Ran out of tokens before answering"

A thinking model spent its whole token budget reasoning. Tick Disable thinking (Settings ▸ Generation), or if you want thinking, raise Max new tokens and set a sensible Thinking limit. For an external server, turn thinking off in that program.

"Model returned an empty caption"

Usually the same cause as above, or the model refused. Try another prompt or model.

Captions describe nothing / ignore the image / say "I can't see an image"

The model is not receiving the image:

• The mmproj field is empty or wrong.
• The model has no vision support. Some model families come in text-only and vision variants.
• External server: the loaded model must be the vision one, with its projector.

HTTP 400 or HTTP 500 in the log

Read the message after it. Typical: the prompt plus image does not fit the context (raise Context per request or lower Resize longest image side), or the model name is wrong (external servers).

"Could not read image"

The file is corrupt or in an unsupported format. The image is marked red and skipped; the rest continue.

Very slow captions

• Thinking is on: disable it.
• Layers are on the CPU: check -ngl and that the log shows the GPU being used.
• The image is huge: lower Resize longest image side.
• Another program is using the GPU.
• With two GPUs and a model that fits on one, use Parallel, not Split.

Some images failed

They are marked red. Fix the cause, then select them and press Caption Selected.

Files and captions

"Could not write … .txt"

The folder is read-only or protected, or the file is open in another program. Check permissions and try again. Dataset folders on cloud-synced or network drives sometimes lock files.

My edit did not save

Edits are saved when you click out of the box. If the app is closed while the box is still active, press Tab or click another card first.

Captions loaded with strange characters

Captions are read and written as UTF-8. Files saved by other tools in a different encoding may show odd characters; re-save them as UTF-8.

I captioned the wrong images

Caption Selected always overwrites. There is no undo, so keep a backup of your .txt files if the old captions matter.

App problems

run.bat closes immediately or says setup failed

Python 3.10+ must be installed and on PATH. Open a terminal and run python --version. Then run the manual steps in Installation to see the error.

Window is blank or the theme looks wrong

Toggle View ▸ Light mode. If that does not help, delete %APPDATA%\RulzCaptioner\settings.json to reset settings.

The app was closed or crashed and the GPU is still full

llama-server.exe is still running in the background. End it in Task Manager (Details tab), or run:

taskkill /F /IM llama-server.exe

Still stuck?

Open an issue and include:

• your GPU(s) and the model/quant you use
• the first 30 lines of View ▸ Log (it contains the command line and any error)
• the steps that led to the problem