Troubleshooting¶
This guide covers common issues when installing, configuring, or using the FCC Agent Team Framework, with specific diagnostic steps and solutions.
Installation Issues¶
pip install fails with "No matching distribution"¶
Symptom:
Cause: Your Python version is below 3.10, or pip is out of date.
Solution:
# Check Python version (must be 3.10+)
python --version
# Upgrade pip
pip install --upgrade pip
# Retry
pip install fcc-agent-team-ext
If you are on Python 3.9 or earlier, upgrade Python. FCC requires 3.10+ due to use of str | None union syntax and importlib.resources.files().
pip install fails with dependency conflicts¶
Symptom:
ERROR: Cannot install fcc-agent-team-ext because these package versions have conflicting dependencies.
Solution: Create a fresh virtual environment to isolate dependencies:
If the conflict is with a specific package (e.g., an older pyyaml pinned by another project), check whether you can upgrade the conflicting dependency or use a separate environment for FCC.
Editable install fails with "pyproject.toml not found"¶
Symptom:
Cause: You are running pip install -e . from the wrong directory.
Solution: Ensure you are in the repository root:
python3-venv not installed on Ubuntu/Debian¶
Symptom:
Solution:
CLI Not Found¶
fcc: command not found¶
Cause 1: Virtual environment not activated.
Cause 2: Package not installed in the active environment.
Cause 3: Scripts directory not on PATH (system Python, no venv).
When installing without a virtual environment, pip may place the fcc script in ~/.local/bin/ (Linux/macOS) or %APPDATA%\Python\Scripts\ (Windows), which may not be on your PATH.
# Find where pip installed the script
python -m site --user-base
# Add to PATH (Linux/macOS)
export PATH="$HOME/.local/bin:$PATH"
Workaround: Run via Python module:
fcc --version shows the wrong version¶
Cause: Multiple installations. An older version in a different environment shadows the new one.
Solution:
# Check which fcc is being used
which fcc
# Check installed version
pip show fcc-agent-team-ext
# If mismatched, uninstall and reinstall
pip uninstall fcc-agent-team-ext
pip install fcc-agent-team-ext
Import Errors¶
ModuleNotFoundError: No module named 'fcc'¶
Cause 1: Package not installed.
Cause 2: Wrong Python interpreter.
# Check which Python you're using
which python
python -c "import sys; print(sys.executable)"
# Make sure it matches the pip that installed fcc
which pip
A common issue is running python (system Python) when FCC was installed in a virtual environment.
Cause 3: Stale .pyc files after upgrading.
find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null
pip install --force-reinstall fcc-agent-team-ext
ImportError: cannot import name 'X' from 'fcc'¶
Cause: You are importing a name that does not exist at the top-level fcc package. Most classes live in submodules.
Check the Architecture page for the module layout.
Data Path Errors¶
FileNotFoundError: data/personas/core_personas.yaml¶
Cause: Your code uses hardcoded paths from v0.1.x. In v0.2.0, data files moved from data/ to src/fcc/data/ and should be accessed via the _resources module.
Solution:
# Replace this:
from pathlib import Path
data_dir = Path("data/personas")
# With this:
from fcc._resources import get_personas_dir
data_dir = get_personas_dir()
See the Migration Guide for a complete walkthrough.
FileNotFoundError when using _resources from a wheel install¶
Cause: The wheel may be missing data files. Verify:
from fcc._resources import get_data_dir
import os
data_dir = get_data_dir()
print(f"Data dir: {data_dir}")
print(f"Exists: {data_dir.exists()}")
print(f"Contents: {os.listdir(data_dir)}")
If the data directory is empty or missing, the wheel was built incorrectly. Reinstall:
If building locally, verify pyproject.toml includes the package-data configuration and run make release-check.
_resources functions return unexpected paths¶
Diagnostic:
from fcc._resources import get_data_dir, get_personas_dir
print(f"Data: {get_data_dir()}")
print(f"Personas: {get_personas_dir()}")
In an editable install, paths point into your source tree (<repo>/src/fcc/data/). In a wheel install, they point into site-packages (<venv>/lib/pythonX.Y/site-packages/fcc/data/). Both are correct behavior.
API Key Problems¶
anthropic.AuthenticationError or openai.AuthenticationError¶
Cause: Missing or invalid API key.
Solution: Set the environment variable before running simulations:
Or create a .env file in the project root (FCC uses python-dotenv to load it automatically):
Simulation works in mock mode but fails with --no-mock¶
Cause: Mock mode (--mock, the default) does not make API calls. When you switch to --no-mock, the engine requires a valid API key for either Anthropic or OpenAI.
Diagnostic:
# Verify the key is set
echo $ANTHROPIC_API_KEY
echo $OPENAI_API_KEY
# Test API connectivity directly
python -c "
import anthropic
client = anthropic.Anthropic()
msg = client.messages.create(
model='claude-sonnet-4-20250514',
max_tokens=10,
messages=[{'role': 'user', 'content': 'ping'}]
)
print(msg.content)
"
Rate limit or quota errors¶
Symptom: anthropic.RateLimitError or openai.RateLimitError
Solution: Reduce max_steps in the simulation or add delays between runs. The 5-node base workflow is the lightest option:
The 24-node complete workflow makes significantly more API calls.
Template Rendering Issues¶
jinja2.TemplateNotFound error¶
Cause: Templates are not being found at the expected location.
Diagnostic:
from fcc._resources import get_templates_dir
import os
templates_dir = get_templates_dir()
print(f"Templates dir: {templates_dir}")
print(f"Exists: {templates_dir.exists()}")
if templates_dir.exists():
for root, dirs, files in os.walk(templates_dir):
for f in files:
print(f" {os.path.join(root, f)}")
If templates are missing, the installation may be corrupted. Reinstall:
Generated documentation contains {{ variable }} literals¶
Cause: Template variables were not resolved. This indicates the template context is missing expected keys.
Diagnostic: Check which persona you are generating docs for:
If the issue is with a custom persona, verify it has the required doc_context fields in its YAML definition:
doc_context:
primary_action: "research"
primary_output: "research reports"
cli_command: "scaffold-rc"
example_scenario: "Research industry best practices for API documentation"
MkDocs build fails with "file not found" warnings¶
Cause: The mkdocs.yml nav references files that have not been generated. Run doc generation first:
Test Failures After Upgrade¶
Tests fail with AssertionError on persona count¶
Symptom:
Cause: A new version added personas, but your tests hardcode the old count.
Solution: Update test assertions to match the current persona count, or use dynamic counts:
from fcc._resources import get_personas_dir
from fcc.personas.registry import PersonaRegistry
registry = PersonaRegistry.from_yaml_directory(get_personas_dir())
assert len(registry) >= 24 # At least 24 personas
Tests fail with import errors after upgrading¶
Solution: Clear caches and reinstall:
Coverage drops below 99% after adding code¶
The CI pipeline enforces a 99% coverage minimum. If you add new code, add corresponding tests:
The --cov-report=term-missing flag shows exactly which lines are not covered.
Protocol Integration Issues¶
A2A Agent Card generation fails with KeyError¶
Symptom:
Cause: The persona loaded into the registry does not have a R.I.S.C.E.A.R. specification. This happens when using a minimal persona YAML without all required fields.
Solution: Ensure every persona has a complete riscear block:
riscear:
role: "Description of the role"
input: "What the persona receives"
style: "Communication style"
constraints:
- "Constraint 1"
expected_output: "What the persona produces"
archetype: "Archetype description"
responsibilities:
- "Responsibility 1"
role_skills:
- "Skill 1"
role_collaborators:
- "Collaborator ID"
adoption_checklist:
- "Checklist item 1"
MCP Server tool call returns "No handler registered"¶
Symptom:
result = server.call_tool("fcc_get_persona", {"persona_id": "RC"})
# result: {"status": "error", "error": "No handler registered for tool: fcc_get_persona"}
Cause: FccMcpServer registers tool definitions but not handlers by default. You must register a handler for each tool.
Solution:
from fcc.protocols.mcp.server import FccMcpServer
server = FccMcpServer()
server.register_tool_handler("fcc_get_persona", my_handler_function)
MCP Server fails with ValueError: Unknown tool¶
Cause: You are trying to register a handler for a tool name that is not in the tool registry.
Solution: List available tools first:
Use one of the listed tool names when calling register_tool_handler().
ProtocolBridge route returns "No route registered"¶
Cause: You are routing a message with a protocol name that has no registered handler.
Solution: Use create_default() for built-in A2A and MCP stubs, or register custom routes:
bridge = ProtocolBridge.create_default(bus)
# Or register your own:
bridge.register_route("my_protocol", my_handler)
Check registered routes with bridge.list_routes().
Knowledge Graph Issues¶
Serialization produces empty output¶
Symptom: serialize_turtle() or serialize_jsonld() returns an empty string or minimal output.
Cause: The graph has no nodes or edges. Common when build_persona_graph() receives an empty registry.
Diagnostic:
print(f"Nodes: {graph.node_count}, Edges: {graph.edge_count}")
stats = graph.stats()
for key, value in stats.items():
print(f" {key}: {value}")
Solution: Verify the registry was loaded correctly:
from fcc._resources import get_personas_dir
from fcc.personas.registry import PersonaRegistry
registry = PersonaRegistry.from_yaml_directory(get_personas_dir())
print(f"Personas loaded: {len(registry)}")
FederatedKnowledgeGraph resolve_entity returns None¶
Cause 1: The target namespace graph is not registered.
Cause 2: Neither the node_id nor the label matches any node in the target graph. Resolution first tries exact node_id match, then case-insensitive label match.
Diagnostic:
target_graph = fed.get_graph("target_namespace")
if target_graph:
for node in target_graph.all_nodes():
print(f" {node.node_id}: {node.label}")
rdflib import error in knowledge graph export¶
Symptom:
Cause: The rdflib package is optional. The built-in serializers (serialize_turtle, serialize_jsonld, etc.) do not require it.
Solution: If you need rdflib-specific features, install it:
Check availability:
RAG Pipeline Issues¶
DocumentChunker produces a single chunk for the entire document¶
Cause: The document does not contain the delimiters expected by the selected strategy. For example, PARAGRAPH strategy splits on double newlines (\n\n), but your document uses single newlines.
Solution: Choose the appropriate strategy for your content:
| Content Type | Strategy | Delimiter |
|---|---|---|
| Prose with paragraphs | PARAGRAPH |
Double newline |
| YAML configuration | YAML_BLOCK |
Top-level keys |
| Python source | CODE_FUNCTION |
def / class boundaries |
| Any text | FIXED_SIZE |
Character count |
from fcc.rag.chunking import DocumentChunker, ChunkingStrategy
# For text without paragraph breaks, use fixed-size
chunker = DocumentChunker(strategy=ChunkingStrategy.FIXED_SIZE, chunk_size=512, overlap=64)
RAG query returns empty or irrelevant sources¶
Cause 1: The index is empty (no documents were added).
Cause 2: The query text has no semantic overlap with the indexed content when using MockEmbeddingProvider. Mock embeddings are hash-based and do not capture real semantic meaning.
Solution for development: Mock mode is suitable for testing pipeline wiring, not semantic quality. For meaningful retrieval, use SentenceTransformerProvider:
from fcc.search.embeddings import SentenceTransformerProvider
provider = SentenceTransformerProvider()
retriever = SemanticRetriever.build_from_chunks(chunks, provider=provider)
SentenceTransformerProvider fails to load¶
Symptom:
Solution:
Note: This requires PyTorch, which is a large dependency (~2 GB). For lightweight deployments, use MockEmbeddingProvider.
Frontend Issues¶
WebSocket connection fails from browser¶
Symptom: Browser console shows WebSocket connection to 'ws://localhost:8765' failed.
Cause 1: The WebSocket bridge is not running.
from fcc.protocols.ws_bridge import WebSocketBridge
bridge = WebSocketBridge(host="localhost", port=8765)
# Must call bridge.start() in an async context
Cause 2: The websockets package is not installed.
Cause 3: Port 8765 is already in use.
Choose a different port:
Cause 4: CORS or mixed-content restrictions. If the frontend is served over HTTPS but the WebSocket uses ws:// (not wss://), browsers will block the connection.
Solution: Either serve everything over HTTP during development, or use a reverse proxy (nginx) to provide TLS termination for the WebSocket endpoint.
D3 visualization does not render¶
Symptom: The React frontend page loads but D3 charts are empty or missing.
Cause 1: The VisualizationBridge is not attached to the StreamManager.
from fcc.protocols.visualization_bridge import VisualizationBridge
from fcc.protocols import StreamManager
viz = VisualizationBridge()
manager = StreamManager(visualization_bridge=viz)
Cause 2: No events are flowing through the stream. Verify:
stats = manager.stream_stats("my_stream")
print(f"Events: {stats['event_count']}, D3 payloads: {stats['d3_payload_count']}")
Cause 3: Frontend is not connecting to the correct WebSocket URL. Check the frontend configuration points to the same host and port as the WebSocket bridge.
Frontend build fails with npm errors¶
Solution: The React frontend requires Node.js 18+:
If you see peer dependency warnings, try:
Getting More Help¶
If your issue is not covered here:
- Search the GitHub Issues.
- Check the FAQ for common questions.
- Open a new issue with:
- Your Python version (
python --version) - Your FCC version (
fcc --versionorpip show fcc-agent-team-ext) - The full error traceback
- Steps to reproduce
Related Pages¶
- Installation -- Setup instructions
- Migration Guide -- Upgrading between versions
- FAQ -- Frequently asked questions
- Testing Guide -- Running and writing tests