Skip to content
Frigg Docs

Troubleshoot semantic and precise retrieval

Semantic and precise retrieval are independent optional accelerators. First determine which layer is degraded; lexical, structural, heuristic navigation, and source reads can remain usable while either accelerator is unavailable.

Semantic retrieval is disabled

Section titled “Semantic retrieval is disabled”

Semantic runtime is off by default. Enable it for both the index pass and the serving process:

Terminal window
FRIGG_SEMANTIC_RUNTIME_ENABLED=true \
FRIGG_SEMANTIC_RUNTIME_PROVIDER=local \
frigg index

If hybrid reports lexical-only ranking while semantic is intentionally off, that is expected. Continue with exact search_text and search_symbol pivots.

A cloud provider fails at startup

Section titled “A cloud provider fails at startup”

Check the required credential:

  • OPENAI_API_KEY for openai
  • GEMINI_API_KEY for google
  • FRIGG_OPENAI_COMPAT_API_KEY, or fallback OPENAI_API_KEY, for openai_compat

For openai_compat, also set FRIGG_SEMANTIC_RUNTIME_OPENAI_COMPAT_ENDPOINT to an absolute HTTP or HTTPS embeddings POST URL. Set FRIGG_SEMANTIC_RUNTIME_MODEL to the backend’s real model id when it differs from the protocol default.

The local model cannot load

Section titled “The local model cannot load”

The local provider prepares missing artifacts automatically. Check:

  1. The directory selected by FRIGG_SEMANTIC_MODEL_CACHE is writable and complete.
  2. The host can download missing artifacts when the cache is cold.
  3. HF_HOME is not redirecting lookup away from Frigg’s prepared cache.

The local MiniLM model is an offline-smoke accelerator. Weak natural-language ranking does not necessarily indicate a load failure; verify readiness, then use exact search for proof.

Semantic results use an old provider or model

Section titled “Semantic results use an old provider or model”

Run a full index pass:

Terminal window
frigg index

Semantic storage is partitioned by repository, provider, and model. Changing only environment variables does not make old partitions current. Also run a full index after changing an openai_compat endpoint to a different vector space or after a Frigg upgrade changes the semantic document envelope.

Semantic failure is degraded or strict

Section titled “Semantic failure is degraded or strict”

Without strict mode, provider failure can degrade hybrid retrieval while deterministic evidence layers continue. With FRIGG_SEMANTIC_RUNTIME_STRICT_MODE=true, the same startup or provider failure becomes a command or service error. Use strict mode only when semantic availability is required.

Precise navigation is unavailable

Section titled “Precise navigation is unavailable”

This is normal when no compatible artifact or generator is available. Continue with heuristic navigation, exact search, structural tools, and source reads. To add precision:

  1. Install the appropriate host generator.
  2. Run frigg index, or provide artifacts under .frigg/scip/.
  3. Inspect workspace for the precise state and generator details.

Frigg does not install generator toolchains.

Precise navigation is partial

Section titled “Precise navigation is partial”

partial means some precise data was ingested but coverage is incomplete. Use precise hits where present, then verify gaps with heuristic navigation and source reads. Inspect ingest diagnostics and .frigg/precise.json excludes when missing paths matter.

A generator failed

Section titled “A generator failed”

Read failure_tool, failure_class, failure_summary, and recommended_action. Typical recoveries are:

  • install a missing executable
  • repair Java, Gradle, Python, Node, Go, Rust, or PHP tool environments
  • increase or address a tool timeout
  • fix invalid or missing generated output
  • use heuristic mode until an upstream tool recovers
  • rerun frigg index after correcting the cause

Generation can report repository-local writes, executed commands, and patch risk. Review those fields before enabling generators in CI.

An artifact is rejected

Section titled “An artifact is rejected”

Artifacts must stay within the repository and configured .frigg/scip/ area. Frigg rejects symlink escapes, paths outside the workspace, invalid protobuf or JSON content, and excluded ingest paths. Regenerate the artifact into a contained path rather than bypassing containment checks.

Section titled “Related”

Source Anchors

Section titled “Source Anchors”
  • ../frigg/README.md
  • ../frigg/docs/operator-runbook.md
  • ../frigg/crates/cli/src/settings/semantic_runtime.rs
  • ../frigg/crates/cli/src/embeddings/provider_factory.rs
  • ../frigg/crates/cli/src/embeddings/local_model.rs
  • ../frigg/crates/cli/src/indexer/semantic.rs
  • ../frigg/crates/cli/src/mcp/types/workspace.rs
  • ../frigg/crates/cli/src/mcp/server/precise_graph/generation.rs
  • ../frigg/crates/cli/src/mcp/server/precise_graph/ingest.rs
  • ../frigg/crates/cli/tests/security.rs