Troubleshooting¶
spum is not found, or an old version runs¶
Check the first matching PATH entry. Homebrew and ~/.local/bin may contain different installations. Restart the shell or refresh its command cache after changing the preferred installation.
Unknown option¶
The prompt-file, system-file, JSON, output-file, quiet and capability-discovery additions require CLI 0.2.2. Upgrade the installation that actually appears first in PATH.
Cannot load a model¶
Check that the file exists, is fully downloaded and uses a compatible architecture and quantization. Confirm its expected checksum where the publisher supplies one. Having a .gguf extension does not prove compatibility.
Missing image projector¶
Supply the matching --mmproj file explicitly. A projector for another model or revision may have incompatible dimensions. Image input is not supported by every language model or backend.
Context or memory failure¶
Reduce --context-size, use a smaller model and close other memory-intensive tasks. Output length and prompt length share the model's context budget. A file may fit on disk and still require more runtime memory than is available.
A prompt file does not work¶
Use UTF-8 plain text, not a PDF or word-processing file. Use either --prompt-file or --prompt, not both. File inputs are limited to 64 MiB. Quote paths containing spaces.
HTTP request fails¶
Check the running process, bind address, port and request JSON. A foreground server stops when its process exits. A vision request also needs a compatible model and projector.
Link loses a worker¶
Check the helper process, network route, matching model file and pairing key. Test spum link status before re-running inference. A generation interrupted by a lost worker should not be treated as a complete response.
AfterGlow produces MIDI but no sound¶
MIDI contains performance events. Open full.mid in a compatible piano instrument or synthesizer to render audio. The MIDI engine is not a speech or audio-waveform generator.
A model gives an incorrect answer¶
Retain the exact prompt, model version, generation options and input. Confirm that the model is suitable for the task. Improving runtime speed does not repair a model's factual or clinical error. Use expert-annotated test data for biomedical accuracy claims.
Mac download warnings¶
Use the current signed release from the Spum website or official tap. If macOS rejects a package, record its filename and version and obtain a fresh official copy. Do not disable Gatekeeper as an installation workaround.