Troubleshooting
Start with the error’s schema address and the smallest affected observation. Confirm its processed structure against the schema before changing model capacity or optimization settings.
| Symptom | Check |
|---|---|
| Constructor rejects an option | Use declared options; parents supply field names. Put notes in description. |
| An input path cannot bind | Names and nesting must match, or the node needs an explicit structural query. |
| A collection exceeds capacity | Check length and choose the intended overflow rule. |
| A mask selector fails | It must return one non-null Boolean per retained owner record. |
| Fitting reports no objectives | Add mask=True or Mask(reconstruct=True) to an active supported field. |
| Fitting reports a missing optimizer | Set model.optimizer = rf.adamw(learning_rate=1e-3) before fitting. |
| Training batches have no selected targets | Check masks, source presence, and target geometry; those batches are skipped. |
| Expected decoded output is absent | Fractional reconstruction policies are inactive in ordinary prediction; use deterministic reconstruction to request outputs. |
| Too many or too few embeddings | Check the selected node and its reduction, including retained outer branch axes. |
| Mutation is rejected during a loop | Move the edit outside forward, predict, or Lightning execution. |
| Compilation disappears after a change | Mutations and checkpoint rebuilds clear it; call compile() again. |
Use Binding Data, Masking, and Embeddings for those contracts.
Separate Events From Metrics
Model construction, mutation, checkpoint restoration, and numerical safeguards produce operational logs. Set RELFLOW_LOG_LEVEL before import or configure the logger directly:
from relflow.logging import configure
configure(level="DEBUG")Supported levels are DEBUG, INFO, WARNING, ERROR, and CRITICAL. This controls relflow event logging. Lightning experiment loggers, progress bars, and evaluation metrics have their own configuration.
When isolating a failure, retain the original field types, relevant nested structure, and mask selectors. Dropping a containing branch can change target geometry, while replacing a null with a missing key can change value state. Use the reported invariant to make the smallest meaningful correction.