Federation Troubleshooting Guide¶

Advanced Tutorial

Duration: 20-30 minutes | Level: Advanced | Prerequisites: Federation tutorial

Common issues and resolution patterns when working with FCC cross-project federation.

Issue 1: Namespace Not Found¶

Symptom: NamespaceRegistry.get("myproject") returns None.

Cause: The namespace is not registered in namespace_registry.yaml.

Resolution:

from fcc.federation.namespaces import NamespaceRegistry, NamespaceConfig

registry = NamespaceRegistry.default_registry()

# Check registered namespaces
print(f"Registered: {registry.all_namespaces()}")

# Register a new namespace
config = NamespaceConfig(
    namespace="myproject",
    prefix="mp",
    base_uri="https://myproject.example.org/",
    version="1.0.0",
    description="My project namespace",
)
registry.register(config)

Issue 2: Entity Resolution Fails¶

Symptom: FederatedKnowledgeGraph.resolve_entity() returns None.

Cause: The entity doesn't exist in the target namespace, or the ID/label doesn't match.

Resolution:

from fcc.knowledge.federation import FederatedKnowledgeGraph

federated = FederatedKnowledgeGraph()

# Check what entities exist in the target namespace
target_graph = federated.get_graph("paom")
if target_graph:
    for node in target_graph.all_nodes()[:10]:
        print(f"  {node.node_id}: {node.label}")

# Entity resolution tries ID first, then label
result = federated.resolve_entity("RC", "fcc", "paom")
if result is None:
    print("Try matching by label instead of ID")

Issue 3: Cross-Namespace Edges Not Appearing¶

Symptom: federated.cross_project_edges() returns empty list.

Cause: Cross-namespace edges must be explicitly added.

Resolution:

# Add cross-namespace edges explicitly
federated.add_cross_edge(
    source_ns="fcc",
    source_id="RC",
    target_ns="paom",
    target_id="archetype_researcher",
)

# Verify
edges = federated.cross_project_edges()
print(f"Cross-namespace edges: {len(edges)}")

Issue 4: Vocabulary Mapping Similarity Too Low¶

Symptom: Mappings flagged for review (similarity < 0.75).

Resolution:

import yaml
from pathlib import Path

# Load and review mappings
path = Path("src/fcc/data/objectmodel/paom_vocabulary_mappings.yaml")
data = yaml.safe_load(path.read_text())

for mapping in data["mappings"]:
    if mapping["similarity"] < 0.75:
        print(f"Review: {mapping['source_term']} → {mapping['target_term']}")
        print(f"  Similarity: {mapping['similarity']}")
        print(f"  Notes: {mapping.get('notes', 'none')}")

Issue 5: Merged Graph Has Duplicate Nodes¶

Symptom: After merge_federated(), node count is higher than expected.

Cause: Same entity exists in multiple namespaces with different IDs.

Resolution: Use vocabulary mappings to establish equivalence before merging, or filter by namespace.

merged = federated.merge_federated()
stats = merged.stats()
print(f"Total nodes: {stats['node_count']}")

# Check for potential duplicates by label
from collections import Counter
labels = Counter(n.label for n in merged.all_nodes())
for label, count in labels.most_common(10):
    if count > 1:
        print(f"Potential duplicate: '{label}' appears {count} times")

Diagnostic Checklist¶

Namespace registered in NamespaceRegistry
Vocabulary mappings loaded for source namespace
Entity IDs match between namespaces (or labels match)
Cross-namespace edges explicitly added
Graph merged after all remote graphs registered
Event bus instrumented for federation debugging