Troubleshooting

Troubleshooting

Can't find model 'en_core_web_sm'

The spaCy English model is not installed in the environment you are running.

python -m spacy download en_core_web_sm

Run it with the same Python that runs Noema. Inside a virtual environment, activate it first. With uv, use uv run python -m spacy download en_core_web_sm.

ImportError mentioning an extra

NoemaRetriever, NoemaLlamaIndexRetriever, Neo4jBackend, RDFBackend and coreference resolution need optional packages. The error names the install command, for example pip install noema-rag[langchain]. See the extras table in Installation.

The first call is very slow, or fails offline

Noema downloads models the first time they are used: the sentence-transformers embedding model, the tiktoken encoding, and any optional models such as the coreference or REBEL models. After that they are cached. On a machine without network access, run once with network access first, or copy the model caches over.

retrieve() returns empty text

• The knowledge base is empty. Check len(kb) and kb.graph.relations.

• The ingested text produced no relations. The default parser needs a subject, verb and object with recognizable entities. Check what was extracted:

  doc = noema.Document(text=text)
  entities = noema.extract_entities(doc)
  relations = noema.extract_relations(doc, entities)

• Sentences use pronouns for the subject. Resolve coreferences first. See Advanced NLP.

The answer is not in the retrieved context

Check context.truncated. If it is True, raise max_tokens. Otherwise raise top_k, and use hops=2 for questions that join facts from different documents. See Retrieval.

Low confidence from compress()

The decoded text differs from the original. Compare result.decoded_text with your input. Decoding is template-based, so scores below 1 are normal even when no fact is lost. Embedding similarity also cannot detect reversed claims. See Round-Trip Validation.

saved_percent is 0

The notation was not shorter than the text, or no facts were extracted. This happens with short, fact-sparse input. Compression helps most on fact-dense text.

Duplicate or wrongly merged entities

Entity merging uses the similarity threshold, default 0.85. If distinct entities merge, raise it. If the same entity stays split, lower it. Set it with KnowledgeBase(similarity_threshold=...). Entities only merge within the same type, so an entity mislabeled by spaCy as a different type will not merge with its other mentions.

Errors after upgrading transformers

Noema pins transformers>=4.40,<5.0, because version 5 breaks fastcoref model loading. Reinstall within the pin.

AttributeError: 'KnowledgeBase' object has no attribute 'ingest_stream'

You are importing an older installed copy of Noema. Check which one with:

python -c "import noema; print(noema.__file__)"

Reinstall from your current source (uv sync or pip install -e .) so that path points to your working copy.

Python version error on install

Noema requires Python 3.13 or newer. Check with python --version.

Something else

Open an issue with the Noema version, Python version, the full error, and a short example that reproduces it.