Frequently Asked Questions

“Backend library is not loaded” error

Problem: You see the error “Backend library is not loaded. Please run install_localLLM() first.”

Solution: Run the installation function after loading the package:

library(localLLM)
install_localLLM()

This downloads the platform-specific backend library. You only need to do this once.

Installation fails on my platform

Problem: install_localLLM() fails to download or install.

Solution: Check your platform is supported: - Windows (x86-64) - macOS (Apple Silicon / ARM64) - macOS (Intel / x86-64) - Linux (x86-64)

If you’re on an unsupported platform, you may need to compile llama.cpp manually.

“Library already installed” but functions don’t work

Problem: install_localLLM() says the library is installed, but generation fails.

Solution: Try reinstalling:

# Force reinstall
install_localLLM(force_reinstall = TRUE)

# Verify installation
lib_is_installed()

“Download lock” or “Another download in progress” error

Problem: A previous download was interrupted and left a lock file.

Solution: Clear the cache directory:

cache_root <- tools::R_user_dir("localLLM", which = "cache")
models_dir <- file.path(cache_root, "models")
unlink(models_dir, recursive = TRUE, force = TRUE)

Then try downloading again.

Download times out or fails

Problem: Large model downloads fail partway through.

Solution: 1. Check your internet connection 2. Try a smaller model first 3. Download manually and load from local path:

# Download with browser or wget, then:
model <- model_load("/path/to/downloaded/model.gguf")

“Model not found” when using cached model

Problem: You’re trying to load a model by name but it’s not found.

Solution: Check what’s actually cached:

cached <- list_cached_models()
print(cached)

Use the exact filename or a unique substring that matches only one model.

Private Hugging Face model fails

Problem: Downloading a gated/private model fails with authentication error.

Solution: Set your Hugging Face token:

# Get token from https://huggingface.co/settings/tokens
set_hf_token("hf_your_token_here")

# Now download should work
model <- model_load("https://huggingface.co/private/model.gguf")

R crashes when loading a model

Problem: R crashes or freezes when calling model_load().

Solution: The model is too large for your available RAM. Try:

1. Use a smaller quantized model (Q4 instead of Q8)
2. Free up memory by closing other applications
3. Check model requirements:

hw <- hardware_profile()
cat("Available RAM:", round(hw$ram_total / 1e9, 1), "GB\n")

“Memory check failed” warning

Problem: localLLM warns about insufficient memory.

Solution: The safety check detected potential issues. Options:

1. Use a smaller model

2. Reduce context size:

   ctx <- context_create(model, n_ctx = 512)  # Smaller context

3. If you’re sure you have enough memory, proceed when prompted

Context creation fails with large n_ctx

Problem: Creating a context with large n_ctx fails.

Solution: Reduce the context size or use a smaller model:

# Instead of n_ctx = 32768, try:
ctx <- context_create(model, n_ctx = 4096)

GPU not being used

Problem: Generation is slow even with n_gpu_layers = 999.

Solution: Check if GPU is detected:

hw <- hardware_profile()
print(hw$gpu)

If no GPU is listed, the backend may not support your GPU. Currently supported:

If your GPU is not listed, install with force_cpu = TRUE to use the CPU build:

install_localLLM(force_cpu = TRUE)

GPU runs out of memory

Problem: GPU runs out of memory during generation.

Solution: Reduce GPU layer count to split the model between GPU and CPU:

# Offload fewer layers to GPU
model <- model_load("model.gguf", n_gpu_layers = 20)

Backend prints too many log messages

Problem: model_load() or context_create() print hardware information, model metadata, or other log lines that clutter the console or appear in knitted documents and R CMD check output.

Solution: Reduce the verbosity level:

# Default (verbosity = 1): warnings only — hardware limits, context size notes
model <- model_load("model.gguf")

# Fully silent loading
model <- model_load("model.gguf",  verbosity = 0)
ctx   <- context_create(model,     verbosity = 0)

Verbosity levels: 0 = silent, 1 = warnings only (default for model_load and context_create), 2 = informational messages, 3 = full debug output. generate() and generate_parallel() already default to verbosity = 0.

Note: backend_init() always prints one line (localLLM backend library loaded successfully.) regardless of verbosity; this cannot be suppressed.

Output is garbled or nonsensical

Problem: The model produces meaningless text.

Solution: 1. Ensure you’re using a chat template:

messages <- list(
  list(role = "user", content = "Your question")
)
prompt <- apply_chat_template(model, messages)
result <- generate(ctx, prompt)

2. The model file may be corrupted - redownload it

Output contains strange tokens like <|eot_id|>

Problem: Output includes control tokens.

Solution: Use the clean = TRUE parameter:

result <- generate(ctx, prompt, clean = TRUE)
# or
result <- quick_llama("prompt", clean = TRUE)

Generation stops too early

Problem: Output is cut off before completion.

Solution: Increase max_tokens:

result <- quick_llama("prompt", max_tokens = 500)

Same prompt gives different results

Problem: Running the same prompt twice gives different outputs.

Solution: Set a seed for reproducibility:

result <- quick_llama("prompt", seed = 42)

With temperature = 0 (default), outputs should be deterministic.

Generation is very slow

Problem: Text generation takes much longer than expected.

Solutions:

1. Use GPU acceleration:

   model <- model_load("model.gguf", n_gpu_layers = 999)

2. Use a smaller model: Q4 quantization is faster than Q8

3. Reduce context size:

   ctx <- context_create(model, n_ctx = 512)

4. Use parallel processing for multiple prompts:

   results <- quick_llama(c("prompt1", "prompt2", "prompt3"))

Parallel processing isn’t faster

Problem: generate_parallel() is no faster than sequential generation.

Solution: Ensure n_seq_max is set appropriately:

ctx <- context_create(
  model,
  n_ctx = 2048,
  n_seq_max = 10  # Allow 10 parallel sequences
)

“GGUF format required” error

Problem: Trying to load a non-GGUF model.

Solution: localLLM only supports GGUF format. Convert your model or find a GGUF version on Hugging Face (search for “model-name gguf”).

Model works in Ollama but not localLLM

Problem: An Ollama model doesn’t work when loaded directly.

Solution: Use the Ollama integration:

# List available Ollama models
list_ollama_models()

# Load via Ollama reference
model <- model_load("ollama:model-name")