Troubleshooting Guide

Here are solutions to some of the most common issues you might encounter while building a VIBE template.

Symptom: "My question isn't showing up in the interview."

This is almost always because VIBE has determined the question is not currently relevant to the final document.

  • Cause 1: It's inside a conditional block. Check your template file (.md or .docx). Is the variable used inside an {% if ... %} block? 

    {% if contract_type == 'enterprise' %}
  The assigned enterprise account manager is {{ enterprise_manager_name }}.
{% endif %}
    In this case, the question for enterprise_manager_name will only appear after the user has selected "enterprise" for contract_type.

  • Cause 2: It's only used by a computable variable. If a computable variable total_price depends on base_price, the question for base_price will only appear if total_price itself is used somewhere in the template. The VIBE engine traces dependencies all the way back from the final document.

  • Troubleshooting Step: Use the "Explain Relevance" link (available in debug mode) next to the question in the left-hand panel. It will tell you exactly which conditions are preventing the question from being shown.

Symptom: "The 'Download Document' button is disabled."

This means the interview is not yet "complete."

  • Cause: There are still one or more required questions that are relevant but have not been answered. Since questions are required by default, look for any visible questions that don't have required: false and provide an answer. Questions with a default do not block completion.

Symptom: "I see a red 'Validation Error' message under my question."

This means the value you entered does not match the rules for that question type.

  • Examples:
    • Typing "abc" into a number field.
    • Leaving a required field empty (remember: questions are required by default unless marked required: false).
    • Entering an invalid email address for an email type question.
  • Solution: Correct the input to match the expected format. The error message will disappear automatically.
  • Note: Required validation typically appears after a field is submitted or has a prior answer, to avoid noisy errors during auto-submit.

Symptom: "I see a big error that says 'Undefined variable'."

This is a template authoring error. It means you have used a variable placeholder, like {{ my_variable }}, in your template file, but you never defined a corresponding question with the ID my_variable in your config.yml.

  • Solution:
    1. Check the variable name for typos in your template file.
    2. If the name is correct, go to your config.yml and add a question block for that variable ID.

Symptom: "Definition 'definition_name' not found" error

This error occurs when you reference a definition that doesn't exist in your config.yml.

  • Cause 1: Typo in definition name. Check that the definition name in your question matches exactly the name in the definitions: section. 

    # ❌ Wrong - case mismatch
definitions:
  person_definition: ...
questions:
  contact:
    type: structured
    definition: Person_Definition  # Capital P - won't match

# ✅ Correct
definitions:
  person_definition: ...
questions:
  contact:
    type: structured
    definition: person_definition

  • Cause 2: Definition not defined yet. Make sure the definition exists in the definitions: section of your config.yml before referencing it.

  • Cause 3: Definition in wrong template. If using a component that references a definition, the definition must be in the host template's config.yml, not the component's.

Symptom: "Circular definition reference detected"

This happens when definitions reference each other in a loop.

  • Example of the problem: 

    definitions:
  a_definition:
    field_b:
      type: structured
      definition: b_definition
  b_definition:
    field_a:
      type: structured
      definition: a_definition  # Creates a circle!

  • Solution: Redesign your definitions to avoid circular references. Consider:

    1. Creating a shared base definition that both can use
    2. Restructuring the data model to eliminate the circular dependency
    3. Using a simpler field type instead of nested structured fields

Symptom: "Input 'field_name' conflicts with definition field"

This occurs when a component tries to override a definition field with a conflicting type.

  • Example of the problem: 

    # In definitions:
person_definition:
  name:
    type: text

# In component.yml:
uses: person_definition
inputs:
  name:  # ❌ Error - conflicts with definition
    type: number  # Different type!
    required: false

  • Solution: Either:

    1. Remove the conflicting input from the component
    2. Use a compatible type and constraints
    3. Rename the field to avoid the conflict
    4. Choose a different definition that doesn't have the conflicting field

Symptom: "Component validation error" or component doesn't load

This happens when there's an issue with your component configuration.

  • Cause 1: Missing component.yml file. For configured components, make sure you have a component.yml file in the component directory.

  • Cause 2: Invalid YAML syntax. Check your component.yml file for syntax errors (indentation, missing colons, etc.).

  • Cause 3: Component not found. Verify the component path is correct and the component directory is in your COMPONENT_SOURCES.

  • Cause 4: Template file missing. Make sure your component has either a template.md or template.docx file.

Symptom: "Namespaced questions not appearing" for components

When using components with definitions, the expected namespaced questions (like alias.field_name) don't appear.

  • Cause 1: Component alias not set. Make sure you're using an explicit alias when inserting the component: 

    {{ insert('contact_card', alias='primary_contact') }}

  • Cause 2: Definition not properly linked. Check that the component's uses: directive points to a valid definition.

  • Cause 3: Questions not used in template. Remember that questions only appear when they're relevant to the final document. Make sure the component is actually used in your template and the namespaced fields are referenced.

Symptom: "Form data not mapping correctly" for structured questions

Data entered in structured or list questions isn't appearing correctly in the template.

  • Cause 1: Incorrect dot notation access. Make sure you're using the correct field names with dot notation: 

    <!-- ❌ Wrong -->
{{ contact_name }}

<!-- ✅ Correct for structured question -->
{{ primary_contact.name }}

  • Cause 2: Field name mismatch. Check that the field names in your template match exactly the field names in your definition.

  • Cause 3: Data not saved properly. Use the browser's developer tools to check if form data is being submitted with the correct field names (should use dot notation like primary_contact.name).

Symptom: "Computable variable not calculating"

A computable variable shows as a placeholder instead of the calculated value.

  • Cause 1: Missing dependencies. The computation depends on variables that haven't been answered yet. Check which variables your computation uses and ensure they have values.

  • Cause 2: Function not found. If using compute_function, make sure:

    • The computations.py file exists in your template directory
    • The function name in computations.py exactly matches the compute_function value
    • There are no syntax errors in the function

  • Cause 3: Expression syntax error. If using compute, check that your Python expression is valid syntax.

  • Troubleshooting: Use the template validation tool: 

    python app.py validate your_template_name

Symptom: "Performance issues" with complex definitions

Template loading or question generation is slow with complex definition structures.

  • Cause: Deep nesting or large numbers of recursive definitions can impact performance.

  • Solutions:

    1. Simplify definition structure - Avoid excessive nesting
    2. Cache clearing - Restart the development server to clear definition cache
    3. Definition optimization - Break large definitions into smaller, focused ones
    4. Limit recursion depth - Avoid definitions that reference many layers of other definitions

General Debugging Tips

  1. Use validation mode: Run python app.py validate template_name to catch configuration errors
  2. Check server logs: Look at the console output for detailed error messages
  3. Test incrementally: Add one definition or component at a time to isolate issues
  4. Verify file structure: Ensure all required files are in the correct locations
  5. Check YAML syntax: Use a YAML validator to verify your configuration files
  6. Browser developer tools: Check the Network tab for form submission issues
  7. Use the developer toolkit: Run vibe-dev --help for systematic troubleshooting commands