Llama() silently accepts and discards `embedding` kwarg; .embed() then raises confusingly
Maintainers usually reply within 1 day
@Anai-Guo is already working on this.
Since Sep 5, 2026.
Assessment
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Newbie friendliness
- 65/100
- Issue type
- Bug
- Clarity
- Clearly specified
- Activity status
- Stale
- Tech stack
- python
- Domain
- backend-api-design
Research direction
The issue is in the Llama.init method in llama_cpp/llama.py, which currently silently swallows the 'embedding' kwarg. Look for the **kwargs handling and the context_params.embeddings assignment. The fix is to either raise a TypeError for unknown kwargs or map 'embedding' to 'embeddings' with a deprecation warning. Test by running the reproduction script to confirm the error, then after your change, ensure .embed() works when 'embedding=True' is passed.
Written by the indexing model from the issue text.
Description
Prerequisites
- I am running the latest code. Development is very rapid so there are no tagged versions as of now.
- I carefully followed the README.md.
- I searched using keywords relevant to my issue to make sure that I am creating a new issue that is not already open (or closed).
- I reviewed the Discussions, and have a new bug or useful enhancement to share.
Expected Behavior
When constructing Llama with the older spelling embedding=True (singular — the parameter name in 0.2.x), one of two things should happen:
- The kwarg is accepted as a deprecated alias of
embeddingsand aDeprecationWarningis emitted, OR - A
TypeErroris raised at construction time, surfacing the issue at the call site rather than swallowing it silently.
Current Behavior
Neither happens. embedding=True is silently swallowed via **kwargs, context_params.embeddings stays at its default False, and the failure surfaces much later — deep inside .embed() — with a misleading error message that suggests the user didn't pass the flag, when in fact they did (just under the historical name).
RuntimeError: Llama model must be created with embeddings=True to call this method
This is especially painful for users integrating older libraries that haven't migrated to the new spelling yet — the error points at the wrong thing.
Environment and Context
- Hardware: x86_64, NVIDIA GeForce RTX 4090
- OS: Windows 10 22H2
- Python 3.12.9
- llama-cpp-python 0.3.36 (CUDA 12.8 prebuilt wheel)
$ python --version
Python 3.12.9
$ pip show llama-cpp-python | findstr Version
Version: 0.3.36
Failure Information (for bugs)
The constructor's **kwargs swallows unknown keyword arguments with no warning, so a typo or stale parameter name produces a delayed, confusing failure rather than an immediate error.
Steps to Reproduce
from llama_cpp import Llama
# Pass the older `embedding` (singular) instead of `embeddings` (plural).
m = Llama(model_path="path/to/model.gguf", embedding=True)
m.embed("hello")
Result:
RuntimeError: Llama model must be created with embeddings=True to call this method
Even though embedding=True was passed at construction. The fix is to either accept embedding as a deprecated alias or to validate kwargs strictly.
Failure Logs
Traceback (most recent call last):
File "...\Lib\site-packages\llama_cpp\llama.py", line 1602, in embed
raise RuntimeError(
RuntimeError: Llama model must be created with embeddings=True to call this method
Hit while integrating Tencent's HY-Motion text-to-motion model — the hymotion package's text encoder still uses the older embedding= spelling, so anyone running it against llama-cpp-python 0.3.x sees this confusing failure at first inference instead of at construction. Workaround in our case is a runtime monkey-patch that translates embedding → embeddings in Llama.__init__, but that doesn't help anyone else.
- Dominant language
- Python
- Stars
- 10.7k
- Forks
- 1.5k
- Avg merge
- 1h 40m
- Merged PRs (30d)
- 5
Getting set up
- No Dockerfile or Docker Compose file
- No pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from abetlen/llama-cpp-python
-
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
abetlen/llama-cpp-python#2424 ·
Maintainers usually reply within 1 day
-
Seven llama_sampler_init_* bindings admit keyword arguments that the ctypes function object silently dropsPossibly taken @Belal0066 claimed this 59 days ago. Open
Difficulty 2/5 1-3 hours Newbie friendliness 88/100
abetlen/llama-cpp-python#2371 ·
Maintainers usually reply within 1 day
-
uv add llama-cpp-python wheels fails for versions above 0.3.30Possibly taken A pull request linked to this issue is open or already merged. Open
Difficulty 2/5 1-3 hours Newbie friendliness 65/100
abetlen/llama-cpp-python#2352 · 1 comment · 3 reactions ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 75/100
abetlen/llama-cpp-python#2314 ·
Maintainers usually reply within 1 day
-
Llama.embed() calls LlamaBatch.add_sequence with old 3-arg signature; missing logits_arrayMay be free again @lxcxjxhx claimed this 136 days ago, and no pull request is open. Open
Difficulty 2/5 1-3 hours Newbie friendliness 65/100
abetlen/llama-cpp-python#2211 · 2 comments ·
Maintainers usually reply within 1 day
All issues in abetlen/llama-cpp-python
Similar issues
-
Difficulty 2/5 1-3 hours Newbie friendliness 64/100
Maintainers usually reply within 1 day
-
area:cli area:security enhancement priority:medium size:small
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
RonaldHensbergen/composable-data-stack#1338 ·
Maintainers usually reply within 1 day
-
area:stdlib effort:S impact:med platform:linux type:bug
Difficulty 2/5 1-3 hours Newbie friendliness 84/100
Maintainers usually reply within 1 day
-
automated endpoint-dead needs-curation
Difficulty 2/5 1-3 hours Newbie friendliness 76/100
almanac-data/climate-almanac#139 ·
Maintainers usually reply within 1 day
-
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
UKGovernmentBEIS/inspect_ai#6695 · 1 comment ·
Maintainers usually reply within 1 day