Skip to main content

Common Errors

Installation​

granite4.1:3b not found​

Error: model "granite4.1:3b" not found

Pull the model before running:

ollama pull granite4.1:3b

Python 3.13: outlines install failure​

error: could not compile `outlines-core`

outlines requires a Rust compiler. Either install Rust or pin Python to 3.12:

uv python pin 3.12
uv add mellea

Intel Mac: torch errors​

Create a Conda environment, install torchvision, then install Mellea inside it:

conda create -n mellea python=3.12
conda activate mellea
conda install 'torchvision>=0.22.0'
uv pip install mellea

Missing optional dependency​

ImportError: The 'hf' backend requires extra dependencies.
Please install them with: pip install 'mellea[hf]'

Each backend has an optional extras group. Install what you need:

pip install "mellea[hf]"         # HuggingFace / local inference
pip install "mellea[litellm]"    # LiteLLM multi-provider
pip install "mellea[watsonx]"    # IBM WatsonX
pip install "mellea[tools]"      # Tool / agent dependencies
pip install "mellea[telemetry]"  # OpenTelemetry tracing + metrics

Ollama connectivity​

Connection refused​

ConnectionError: Could not connect to Ollama at http://localhost:11434

Ollama is not running. Start it:

ollama serve

Then verify it is reachable:

curl http://localhost:11434/api/version

Wrong Ollama URL​

If Ollama is running on a non-default host or port, pass the URL explicitly:

from mellea.backends.ollama import OllamaModelBackend

m = MelleaSession(OllamaModelBackend(base_url="http://my-ollama-host:11434"))

Requirements and sampling​

Requirements always failing — output looks fine​

If the model keeps retrying but the output looks correct, the validation function may be too strict. Inspect what is being rejected:

from mellea import start_session
from mellea.stdlib.requirements import req

m = start_session()
result = m.instruct(
    "Write a haiku.",
    requirements=[req("Must be exactly 17 syllables")],
    return_sampling_results=True,
)

print(f"Success: {result.success}")
for i, (generation, validations) in enumerate(
    zip(result.sample_generations, result.sample_validations)
):
    print(f"\nAttempt {i + 1}:")
    print(f"  Output: {generation.value}")
    for requirement, validation in validations:
        print(f"  {requirement.description}: {validation._result} — {validation._reason}")

return_sampling_results=True makes instruct() return a SamplingResult instead of a ModelOutputThunk. Use result.success to check whether the budget was exhausted without a passing output.

Budget exhausted — result.success is False​

The model failed all loop_budget attempts. Options:

  • Increase loop_budget:

    from mellea.stdlib.sampling import RejectionSamplingStrategy

    strategy = RejectionSamplingStrategy(loop_budget=5)
    result = m.instruct("...", requirements=[...], strategy=strategy)

  • Simplify or relax the requirement.

  • Provide a more specific validation function that gives the model useful feedback via ValidationResult.reason — the reason string is passed back to the model on retry.

  • Switch to SOFAISamplingStrategy to escalate to a stronger model when the primary model fails.

PreconditionException from @generative​

mellea.stdlib.components.genstub.PreconditionException

A precondition check in a @generative function failed before generation. This is intentional — the function declared that its inputs do not meet a precondition. Check the function's @precondition decorators and validate your inputs before calling.

Agents and tools​

react() raises RuntimeError​

RuntimeError: could not complete react loop in N iterations

The ReACT loop exhausted its loop_budget without finding a final answer. Either increase the budget or check that the tool functions are returning the information the model needs to reach a conclusion.

Tool not called / wrong tool called​

If the model is not calling tools as expected:

  • Verify ModelOption.TOOLS is set in the session's model options.
  • Check the tool's docstring — the model uses it to decide when to call the tool. A vague or absent docstring leads to poor tool selection.
  • Use guardian_check(context, backend, criteria="function_call") from the Guardian Intrinsics to detect function call hallucinations.

Async​

RuntimeError: no running event loop​

RuntimeError: no running event loop

You are calling a synchronous Mellea method from inside an async function. Switch to the async method (ainstruct, achat, aact) or wrap in asyncio.run() if you are at the top level.

asyncio.run() inside a Jupyter notebook​

Jupyter notebooks already run an event loop. Use await directly or install nest_asyncio:

pip install nest_asyncio
import nest_asyncio
nest_asyncio.apply()

Guardian / safety validation​

Guardian Intrinsics (guardian_check(), policy_guardrails(), factuality_detection(), factuality_correction()) require LocalHFBackend with an IBM Granite model. See Safety Guardrails for full usage.

guardian_check() returns unexpected scores​

  • Double-check the criteria argument — use a key from CRITERIA_BANK (e.g. "harm", "groundedness") or a free-text criteria string.
  • For groundedness checks, attach source documents via documents=[Document(...)] on the Message("assistant", ...) in the evaluation context — not as a separate user message.
  • Scores below 0.5 are safe; at or above 0.5 indicates risk detected.

Deprecated GuardianCheck warnings​

DeprecationWarning: GuardianCheck is deprecated as of version 0.4.
Use the Guardian Intrinsics instead

Replace GuardianCheck / GuardianRisk imports with the Guardian Intrinsics API. See Safety Guardrails for migration guidance.

Getting more help​

See also: Quick Start | Inference-Time Scaling | Safety Guardrails