RelationResponse validation fails when from_entity.permalink is null

[phernandez]

Problem

When viewing entities that have relations to entities with null permalinks, the API returns a 500 error:

500: Internal proxy error: 1 validation error for EntityResponseV2
relations.0.from_entity.permalink
  Input should be a valid string [type=string_type, input_value=None, input_type=NoneType]

Root Cause

In src/basic_memory/schemas/response.py, the RelationResponse schema has:

from_id: Permalink = Field(
    validation_alias=AliasChoices(
        AliasPath("from_entity", "permalink"),  # Tries this FIRST
        "from_id",
    )
)

When from_entity.permalink is None (which is valid for imported notes without permalinks enabled), Pydantic fails validation because from_id is typed as Permalink (non-nullable Annotated[str, MinLen(1)]).

Reproduction

1. Import notes from a local environment where permalinks were not enabled
2. Create a relation between an entity with a permalink and one without
3. Try to view the entity with the relation via /v2/projects/{id}/knowledge/entities/{id}
4. 500 error occurs

Evidence

From production Logfire trace for user with imported notes:

• 212 out of 345 entities (61%) have null permalinks
• Viewing entity 346 fails because relation id 205 references entity 42 which has permalink: null

Proposed Fix

Either:

1. Make from_id optional: from_id: Optional[Permalink] = Field(...)
2. Or add proper fallback handling when from_entity.permalink is None (use entity title or file_path as fallback)

Option 2 is preferred since it maintains backwards compatibility and provides a meaningful value.

[claude]

Claude finished @phernandez's task in 3m 15s —— View job • claude/issue-483-20251229-2348 • Create PR ➔

---

Issue #483 Analysis & Fix Complete

Task List

• Search for duplicate issues
• Read schema files to verify the problem
• Classify issue type, priority, and complexity
• Add appropriate labels
• Implement fix
• Add test for null permalink case
• Commit and push changes
• Provide PR creation link

Analysis

Root Cause:

• Permalink type is Annotated[str, MinLen(1)] (non-nullable)
• Entity.permalink can return None when permalinks are disabled (_permalink == "")
• RelationResponse.from_id uses AliasPath("from_entity", "permalink") but was typed as non-optional Permalink
• When from_entity.permalink is None, Pydantic validation fails with 500 error

Issue Classification:

• Type: Bug (validation error causing 500 responses)
• Priority: High (affects production users - 61% of entities have null permalinks)
• Component: API schemas/validation
• Complexity: Simple (minimal type change + test)

Changes Made

1. Schema Fix (src/basic_memory/schemas/response.py:67-75)

# Changed from non-optional to optional with default
from_id: Optional[Permalink] = Field(
    validation_alias=AliasChoices(
        AliasPath("from_entity", "permalink"),
        "from_id",
    ),
    default=None,  # Added default for null permalinks
)

2. Test Coverage (tests/schemas/test_schemas.py:94-112)
Added test_relation_response_with_null_permalink() to verify the fix handles null permalinks correctly without validation errors.

Solution Rationale

Chose Option 1 (make from_id optional) because:

• Matches the existing pattern for to_id field which is already Optional[Permalink]
• Minimal change with clear semantics
• Maintains backwards compatibility - existing valid permalinks still work
• Database schema already allows null values
• Simpler than Option 2 (fallback logic) and addresses the root cause directly

---

Branch: claude/issue-483-20251229-2348 |