# What Happens When the Scope Is Missing During Read, Search, or Embed Operations in ai-memory

> Learn what happens when the scope is missing in ai-memory read search or embed operations. Discover the StoreError::MissingScope error and why database access is prevented.

- Repository: [Fabio Akita/ai-memory](https://github.com/akitaonrails/ai-memory)
- Tags: how-to-guide
- Published: 2026-08-22

---

**When the scope is missing during read, search, or embed operations in ai-memory, the system immediately returns a `StoreError::MissingScope` error after the resolver fails to locate the workspace-project tuple in the SQLite `scopes` table, preventing any database access.**

The ai-memory repository provides a scoped storage layer for AI applications, where every data access operation is bound to a specific workspace and project context. Understanding how the system handles missing scope references is critical for implementing proper error handling in production deployments.

## Scope Resolution Mechanism in ai-memory

Before executing any read, search, or embed operation, ai-memory validates the scope through the **scope resolver** implemented in [`crates/ai-memory-core/src/workspace.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-core/src/workspace.rs).

The resolver queries the SQLite `scopes` table using the `resolve_existing_scope` function to verify that the requested workspace and project combination exists. If the tuple is not found, the function returns the error variant `ScopeError::Missing` immediately.

## Error Propagation Through the System Stack

Once the core resolver detects a missing scope, the error propagates through distinct layers with specific transformations at each boundary.

### Store Layer Translation

The public store API in [`crates/ai-memory-store/src/lib.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/lib.rs) translates the core `ScopeError::Missing` into `StoreError::MissingScope`. This conversion occurs in the implementation of `read_page`, `search_page`, and `embed_page` methods before any database access occurs, ensuring the error surfaces at the API boundary with a consistent type.

### MCP HTTP Response Mapping

The MCP route handlers in [`crates/ai-memory-mcp/src/routes.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/routes.rs) map `StoreError::MissingScope` to an HTTP **404 Not Found** response. The client receives a JSON body formatted as `{"error":"scope not found"}` to indicate the specific resource context that could not be located.

## Operation-Specific Failure Behavior

All three primary operations—read, search, and embed—follow identical failure paths when encountering missing scopes, aborting before touching any data indexes.

### Read Operations with `read_page`

When calling `read_page` with an invalid scope, the operation aborts before querying the page content store. The function returns `Err(StoreError::MissingScope)` immediately after the resolver check fails, preventing any filesystem or database access for content retrieval.

### Search Operations with `search_page`

The full-text search implementation performs scope resolution prior to accessing the FTS indexes. A missing scope prevents the search query from executing, returning the same error variant without touching the search index or performing any tokenization operations.

### Embed Operations with `embed_page`

Vector embedding requests also validate scope existence before accessing the vector store. The `embed_page` function fails fast with `MissingScope` rather than attempting to generate embeddings or query the vector index for non-existent contexts.

## Handling Missing Scope Errors in Application Code

Applications integrating ai-memory should explicitly handle `StoreError::MissingScope` to provide graceful degradation and user-friendly error messages.

```rust
// Reading a page with explicit scope error handling
use ai_memory_store::{Client, StoreError};

let client = Client::new(...);
match client.read_page(workspace_id, project_id, "some/page.md") {
    Ok(content) => println!("Page: {}", content),
    Err(StoreError::MissingScope) => eprintln!("Error: scope does not exist"),
    Err(e) => eprintln!("Other error: {}", e),
}

```

```rust
// Performing a full-text search with missing scope protection
match client.search(
    workspace_id,
    project_id,
    "keyword",
    /* pagination parameters */
) {
    Ok(results) => println!("Found {} hits", results.len()),
    Err(StoreError::MissingScope) => eprintln!("Cannot search – scope missing"),
    Err(e) => eprintln!("Search error: {}", e),
}

```

```rust
// Requesting embeddings with scope validation
match client.embed(
    workspace_id,
    project_id,
    "The quick brown fox…",
) {
    Ok(vec) => println!("Embedding size: {}", vec.len()),
    Err(StoreError::MissingScope) => eprintln!("Embedding failed – missing scope"),
    Err(e) => eprintln!("Embedding error: {}", e),
}

```

## Summary

- **Validation occurs first**: Every read, search, and embed operation validates scope existence via `resolve_existing_scope` in [`crates/ai-memory-core/src/workspace.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-core/src/workspace.rs) before accessing data stores or indexes.
- **Immediate failure**: Missing scopes trigger `ScopeError::Missing` at the core level, which propagates as `StoreError::MissingScope` through the store layer without retry or fallback logic.
- **No automatic creation**: The system does not create default scopes or proceed with unscoped queries; it fails fast to prevent data leakage and ensure strict isolation.
- **HTTP 404 mapping**: MCP endpoints translate missing scope errors into standard HTTP 404 responses with descriptive JSON payloads for REST clients.
- **Consistent across operations**: Read, search, and embed operations share identical scope validation logic and error handling paths, ensuring predictable behavior regardless of operation type.

## Frequently Asked Questions

### What error type does ai-memory return when the scope is missing?

The system returns `StoreError::MissingScope` at the store API level. This originates from `ScopeError::Missing` in the core workspace resolver and propagates through the stack without modification until the presentation layer maps it to an HTTP 404 response.

### Does ai-memory create a default scope automatically if one is missing?

No. The system implements fail-fast behavior. If the `(workspace, project)` tuple does not exist in the SQLite `scopes` table, the operation aborts immediately with an error rather than creating a fallback scope, proceeding with unscoped access, or attempting automatic scope creation.

### Which HTTP status code does the MCP server return for missing scope errors?

The MCP route handlers in [`crates/ai-memory-mcp/src/routes.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-mcp/src/routes.rs) map `StoreError::MissingScope` to HTTP **404 Not Found**. The response includes a JSON payload with the message `"scope not found"` to indicate the specific failure reason to API consumers.

### Can read, search, and embed operations proceed without a valid scope?

No. All three operations require valid scope resolution before executing. The `read_page`, `search_page`, and `embed_page` functions in [`crates/ai-memory-store/src/lib.rs`](https://github.com/akitaonrails/ai-memory/blob/main/crates/ai-memory-store/src/lib.rs) each perform scope validation as their first operation, ensuring no database queries execute against content stores, FTS indexes, or vector indexes when the scope is absent.