Troubleshooting Guide

Common Issues and Solutions

dcc.Slider Component TypeError - Unexpected Keyword Argument

Problem: Error when navigating to CMC view: TypeError: The dcc.Slider component received an unexpected keyword argument: 'tipo'

Root Cause: The obtener_config_control() function returns a dictionary that includes a tipo field (used internally to identify control type), but dcc.Slider doesn't accept this argument.

Solution: Filter out the tipo field before passing configuration to dcc.Slider:

# Wrong - passes all fields including 'tipo'
dcc.Slider(**{**obtener_config_control("alpha"), "id": "slider-alpha", "value": value})

# Correct - filter out 'tipo' field
dcc.Slider(id="slider-alpha", value=value, **{k: v for k, v in obtener_config_control("alpha").items() if k != "tipo"})

Key Learning: Always validate that component arguments match the expected interface. Internal configuration fields should be filtered before passing to Dash components.

---

Plotly Graphs Not Appearing When Loading from Cache

Problem: Interactive Plotly graphs appear when calculated directly in a view, but disappear when loading from cache or executing from "Calcular Todo".

Root Cause: Only PNG files were being saved with fig.write_image(), but JSON files are required for dcc.Graph to display interactive Plotly figures.

Solution: Save BOTH formats when caching Plotly figures:

# PNG for static export
fig.write_image(str(png_path), width=1200, height=600)
# JSON for interactive display
fig.write_json(str(json_path))

Key Learning: Plotly figures require JSON format for interactivity in Dash. Always save both PNG (export) and JSON (display) when caching.

---

View Reloading After Calculation

Problem: After clicking "Calcular" in CMC view, results appear briefly then the view reloads showing cached results instead of fresh ones.

Root Cause: Navigation callback had Input("menu-guardar-estructura", "n_clicks") which triggered whenever parameters were saved, causing unwanted view reloads.

Solution: Remove non-navigation menu items from navigation callback Inputs. Only include menu items that explicitly change views:

@app.callback(
    Output("contenido-principal", "children"),
    Input("btn-inicio", "n_clicks"),
    Input("menu-calculo-mecanico", "n_clicks"),
    # DO NOT include: Input("menu-guardar-estructura", "n_clicks")
    State("estructura-actual", "data"),
)

Key Learning: Navigation callbacks should ONLY respond to navigation actions, not to save/update actions.

---

Callbacks Triggering on Page Load

Problem: Callbacks execute automatically when page loads, causing unnecessary computations or UI updates.

Solution: Add prevent_initial_call=True to callback decorator:

@app.callback(
    Output("badge-estructura-actual", "children"),
    Input("estructura-actual", "data"),
    prevent_initial_call=True
)

---

Results Disappearing on Error

Problem: When calculation fails, previous results are cleared from the view.

Solution: Return dash.no_update instead of empty components on error:

try:
    # calculation logic
    return results_html, True, "Éxito", "Cálculo completado", "success", "success"
except Exception as e:
    return dash.no_update, True, "Error", f"Error: {str(e)}", "danger", "danger"

---

Multiple Callbacks Updating Same Output

Problem: Dash raises error when multiple callbacks try to update the same Output.

Solution: Use allow_duplicate=True on all but the first callback:

@app.callback(
    Output("resultados-cmc", "children", allow_duplicate=True),
    Input("btn-calcular-cmc", "n_clicks"),
    prevent_initial_call=True
)

---

State vs Input Confusion

Problem: Callback triggers when data changes even though it shouldn't.

Key Difference:

• Input: Triggers callback when value changes
• State: Provides value but does NOT trigger callback

Example:

@app.callback(
    Output("contenido-principal", "children"),
    Input("menu-calculo-mecanico", "n_clicks"),  # Triggers on click
    State("estructura-actual", "data"),  # Provides data but doesn't trigger
)

---

Debugging Tips

Identify Which Callback is Triggering

Use dash.callback_context to see what triggered the callback:

ctx = dash.callback_context
if ctx.triggered:
    trigger_id = ctx.triggered[0]["prop_id"].split(".")[0]
    print(f"Triggered by: {trigger_id}")

Prevent Unwanted Triggers

Return dash.no_update early if trigger is not expected:

ctx = dash.callback_context
if not ctx.triggered:
    return dash.no_update

trigger_id = ctx.triggered[0]["prop_id"].split(".")[0]
if trigger_id not in ["expected-button-1", "expected-button-2"]:
    return dash.no_update

Cache Management

When results show as "from cache" unexpectedly:

1. Check if CalculoCache.verificar_vigencia() is being called
2. Ensure cache loading doesn't verify vigencia when you want to preserve results
3. Remove vigencia checks from navigation callbacks to always show cached results

Missing Function Arguments

Problem: Function call fails with "missing required positional arguments" error.

Example: CalculoCache.guardar_calculo_sph() called with single dict argument instead of separate parameters.

Solution: Check function signature and pass arguments individually:

# Wrong
CalculoCache.guardar_calculo_sph(nombre, calculo_dict)

# Correct
CalculoCache.guardar_calculo_sph(nombre, parametros, resultados, desarrollo_texto)

Key Learning: Always verify function signatures when calling from different contexts (direct call vs. orchestrated call).

---

Orchestrated Calculations

Pattern: When implementing "Calcular Todo" or similar orchestration:

1. Reuse existing calculation functions from individual controllers
2. Reuse existing result generation functions from individual views
3. Don't duplicate logic - call the same functions used in individual views
4. Ensure all cache operations save complete data (including JSON for Plotly)
5. Test that cached results display identically whether calculated individually or orchestrated

Anti-pattern: Creating separate calculation logic for orchestrated workflows leads to inconsistencies.

---

Performance Optimization

Avoid Redundant Callbacks

• Don't add Inputs that aren't related to the callback's purpose
• Use prevent_initial_call=True liberally
• Return dash.no_update when no update is needed

List Building for Dash Components

Problem: Components not appearing when using .extend([component1, component2]).

Solution: Use .append() for each component individually:

# Preferred
resultados.append(html.H6("Title"))
resultados.append(dcc.Graph(figure=fig))

# Avoid
resultados.extend([html.H6("Title"), dcc.Graph(figure=fig)])

Key Learning: Individual .append() calls ensure proper component registration in Dash's component tree.

Minimize File I/O in Callbacks

• Cache file reads in memory when possible
• Avoid reading navigation state file on every callback
• Use Dash Stores for frequently accessed data

Async Operations

For long-running calculations, use threading to avoid blocking:

import threading

def guardar_async():
    CalculoCache.guardar_calculo_cmc(...)

threading.Thread(target=guardar_async, daemon=True).start()

---

Console Capture Best Practices

Implementing stdout/stderr Redirection

1. Complete Interface: Implement all file-like methods (write, flush, isatty, fileno)
2. Delegation: Use __getattr__ to delegate unknown attributes to original stdout
3. Thread Safety: Use locks when accessing shared buffer
4. Memory Management: Limit buffer size to prevent memory issues
5. Avoid Recursion: Don't call print() inside buffer manipulation methods

Dash Callbacks for View-Specific Components

1. Exception Handling: Wrap callback logic in try-except to handle missing components
2. No Interval: Avoid dcc.Interval for view-specific updates - use manual refresh
3. prevent_initial_call=False: Load content when entering view
4. dash.no_update: Return when component doesn't exist or error occurs

Lessons Learned

Callback Conflicts - Unique IDs for Multiple Modal Systems

Context: Implementing family structures feature with modal editing similar to tabla_parametros.

Issue: DuplicateCallback error when both familia_controller.py and tabla_parametros_controller.py used same modal IDs (modal-parametro, modal-body-parametro, modal-celda-info).

Root Cause: Multiple controllers defining callbacks with identical Output IDs causes Dash to reject duplicate callback registration.

Resolution:

1. Unique ID prefixes: Use familia-modal-* for family modals vs modal-* for parameter table modals
2. Unique button types: Use familia-opcion-btn, familia-bool-btn vs opcion-btn, bool-btn
3. Component ID consistency: Update both controller callbacks AND component creation to use same unique IDs

Critical Pattern:

# Controller callbacks
@app.callback(
    [Output("modal-familia-parametro", "is_open"),
     Output("modal-familia-body-parametro", "children")],
    [Input("tabla-familia", "active_cell"),
     Input("modal-familia-confirmar", "n_clicks")]
)

# Component creation
dbc.Modal([
    dbc.ModalBody(id="modal-familia-body-parametro"),
    dbc.ModalFooter([
        dbc.Button("Confirmar", id="modal-familia-confirmar")
    ])
], id="modal-familia-parametro")

# Button types in modal content
dbc.Button(
    opcion,
    id={"type": "familia-opcion-btn", "value": opcion}
)

Key Takeaway: When implementing similar features, always use unique ID prefixes to avoid callback conflicts. Apply prefix consistently across:

• Controller callback Inputs/Outputs
• Component creation IDs
• Pattern-matching component types

Files Modified:

• controllers/familia_controller.py - Unique callback IDs
• components/vista_familia_estructuras.py - Unique component IDs

---

Family Structures Implementation - Button Controls

Context: Adding control buttons (Agregar/Eliminar Estructura, Guardar Familia, Cargar Columna) to family structures view.

Implementation Pattern:

1. Component Creation: Add buttons in crear_botones_control_familia() function
2. Callback Registration: Add callbacks in register_callbacks(app) function in controller
3. Dynamic Table Updates: Use allow_duplicate=True for table columns and data outputs
4. State Management: Use table columns and data as State inputs for modifications

Button Functionality:

• Agregar Estructura: Adds new column (Estr.N+1), copies values from last existing column
• Eliminar Estructura: Removes highest numbered column, prevents deletion if only one remains
• Column Numbering: Finds next available number, handles gaps in sequence
• Data Preservation: Maintains all parameter values when adding/removing columns

Key Pattern:

# Component
dbc.Button("Agregar Estructura", id="btn-agregar-estructura", color="success")

# Controller
@app.callback(
    [Output("tabla-familia", "columns", allow_duplicate=True),
     Output("tabla-familia", "data", allow_duplicate=True)],
    Input("btn-agregar-estructura", "n_clicks"),
    [State("tabla-familia", "columns"), State("tabla-familia", "data")]
)

Files Modified:

• components/vista_familia_estructuras.py - Added button controls
• controllers/familia_controller.py - Added button callbacks

Lessons Learned

Dual Format Storage for Plotly

Context: Implementing "Calcular Todo" feature that orchestrates multiple calculations.

Issue: Plotly graphs appeared when calculated in individual views but not when executed from orchestra