Skip to content

Common Beginner Mistakes (and their fixes)

FAQ-style catalogue of the 15 errors new FCC users hit most often. Each entry follows the same pattern: problem -> symptom -> root cause -> fix -> prevention tip.

If your issue isn't here, check the FAQ or search the notebooks.

Installation

M1: Forgetting the editable install

  • Problem: You cloned the repo but import fcc fails.
  • Symptom: ModuleNotFoundError: No module named 'fcc'
  • Root cause: You skipped pip install -e ., or you're not inside the venv that has FCC.
  • Fix: 
    source .venv/bin/activate
pip install -e .
  • Prevention: Make source .venv/bin/activate the first thing you do when you open a terminal. Add a shell alias if you forget often.

M2: Wrong Python version

  • Problem: Install completes but imports fail with odd syntax errors.
  • Symptom: SyntaxError: invalid syntax on valid-looking code, or pip install reports "requires-python >= 3.10".
  • Root cause: Default python is 3.8 or 3.9.
  • Fix: Use python3.10 or later explicitly: 
    python3.10 -m venv .venv
  • Prevention: Check with python --version before creating the venv.

M3: Installing without optional extras

  • Problem: Notebooks or Streamlit apps fail with ImportError.
  • Symptom: ImportError: streamlit when running apps/streamlit/*.py.
  • Root cause: Extras groups ([streamlit], [notebooks], [rag], [full]) aren't installed by the base pip install -e ..
  • Fix: 
    pip install -e ".[full]"
  • Prevention: When in doubt, use [full] -- it pulls in every optional dependency the framework supports.

CLI usage

M4: Running fcc outside an FCC project

  • Problem: fcc validate fails even though FCC is installed.
  • Symptom: No fcc_config.yaml found in .
  • Root cause: Most fcc subcommands require either --dir <project> or being cd'd into a project created by fcc init.
  • Fix: 
    fcc init --name my-project
cd my-project
fcc validate
  • Prevention: Remember that fcc init is the starting point; other commands assume a project layout.

M5: Mixing --name and positional args

  • Problem: fcc add-persona errors unexpectedly.
  • Symptom: Error: Missing argument 'NAME'.
  • Root cause: name is positional, --phase and --id are flags.
  • Fix: 
    fcc add-persona "Custom Analyst" --phase Find --id CA
  • Prevention: Always check fcc <subcommand> --help before using it.

Persona YAML authoring

M6: Missing required R.I.S.C.E.A.R. fields

  • Problem: Custom YAML fails to load.
  • Symptom: jsonschema.ValidationError: 'archetype' is a required property
  • Root cause: R.I.S.C.E.A.R. has 10 mandatory components. Skipping any breaks validation.
  • Fix: Populate every component: role, input, style, constraints, expected_output, archetype, responsibilities, role_skills, role_collaborators, role_adoption_checklist.
  • Prevention: Start from fcc add-persona, which scaffolds a complete YAML, then edit.

M7: YAML indentation errors

  • Problem: Persona loads but has empty fields.
  • Symptom: persona.riscear.role is None.
  • Root cause: Tab vs space mix, or a riscear: child indented at the same level as riscear:.
  • Fix: Use 2 spaces for every indent level. No tabs. Nested children must be indented deeper than their parent.
  • Prevention: Use an editor that shows whitespace (VS Code, Vim with set list).

M8: Unknown category

  • Problem: Persona loads but doesn't appear in by_category() results.
  • Symptom: registry.by_category("my_custom") returns [].
  • Root cause: Category doesn't match any of the 20 core categories and wasn't registered as custom.
  • Fix: Either use a known category (core, integration, governance, etc.) or register your own with registry.register_category().
  • Prevention: Run registry.categories() first to list valid options.

Simulation running

M9: Expecting AI output in mock mode

  • Problem: Trace steps contain placeholder strings like "[MOCK] Created outline".
  • Symptom: "Why is the output so generic?"
  • Root cause: You are in mode="mock", which is deterministic and does not call any real LLM.
  • Fix: Set mode="ai" and export an API key (ANTHROPIC_API_KEY, OPENAI_API_KEY, or point OLLAMA_BASE_URL at a local server).
  • Prevention: Mock mode is the correct default for testing and CI. Reserve AI mode for genuine content generation.

M10: Forgetting to source .env

  • Problem: You set the API key but FCC still uses mock.
  • Symptom: Console says mode=ai but output looks mocked.
  • Root cause: API key is in .env but python-dotenv wasn't loaded, or the key was exported in another shell.
  • Fix: 
    set -a && source .env && set +a
python -c "import os; print(os.environ['ANTHROPIC_API_KEY'][:10])"
  • Prevention: Use python-dotenv's load_dotenv() at the top of scripts and notebooks.

M11: Scenario not found

  • Problem: scenarios.get("my_scenario") raises KeyError.
  • Symptom: KeyError: 'my_scenario'.
  • Root cause: Scenario file isn't in a directory the loader scans, or the filename doesn't match the id: field.
  • Fix: Use ScenarioLoader.from_directory("my_scenarios/") and ensure the id: field in YAML matches what you look up.
  • Prevention: List available IDs first: list(scenarios.all()).

Interpreting traces

M12: Confusing phase with action_type

  • Problem: You expect step.phase == "scaffold" but it's "CREATE".
  • Symptom: Your filtering logic skips every step.
  • Root cause: phase is one of FIND/CREATE/CRITIQUE. The 6 action types (scaffold, refactor, debug, test, compare, document) live under step.action.type.
  • Fix: 
    [s for s in trace.steps if s.action.type == "scaffold"]
  • Prevention: Remember the hierarchy: phase -> persona -> action_type -> output.

M13: Reading trace.steps before the run completes

  • Problem: Trace looks empty.
  • Symptom: len(trace.steps) == 0.
  • Root cause: You captured the trace object before calling run(), or you ran asynchronously and the future isn't resolved.
  • Fix: Always destructure trace = engine.run(scenario) on a single line.
  • Prevention: For async runs, await the coroutine before reading.

Plugin setup

M14: Plugin package not picked up

  • Problem: You pip installed a plugin but PluginRegistry.discover() doesn't list it.
  • Symptom: Plugin count unchanged after install.
  • Root cause: Plugin didn't declare a fcc.plugins entry point in its pyproject.toml, or you installed into a different venv.
  • Fix: Check the plugin's pyproject.toml: 
    [project.entry-points."fcc.plugins"]
my_plugin = "my_plugin.module:MyPlugin"
  • Prevention: Follow the plugin development guide template exactly.

M15: Plugin type mismatch

  • Problem: A plugin loads but its methods are never invoked.
  • Symptom: plugin.on_event() is never called even though events fire.
  • Root cause: Plugin declared type persona but implements EventSubscriberPlugin behavior. FCC routes by declared type.
  • Fix: Change plugin_type = "subscriber" (or whichever of the 11 types matches the interface you implement).
  • Prevention: Read plugin-development.md to understand the 11 plugin types (personas, engines, templates, scorers, validators, providers, governance, scenarios, workflows, subscribers, vocabulary_providers) before writing your own.