The primary tool for debugging errors in Nano Banana 2 is structured logging. The library emits JSON-formatted log entries for all significant lifecycle events, including stage initialization, record processing errors, plugin failures, and pipeline shutdown. Each log entry includes a timestamp, log level, pipeline stage identifier, and a context object with relevant details about the error. You can route these logs to any logging backend your application uses—stdout for containerized environments, a log aggregation service, or a local file—by configuring the logging output in the pipeline YAML file.
For errors that occur inside transformation functions written by the developer, Nano Banana 2 wraps exceptions and includes the original traceback in the log output. By default, a stage error causes the affected record to be sent to the pipeline’s dead-letter queue rather than stopping the entire pipeline. You can inspect the dead-letter queue contents using the CLI tool (nb2 dlq inspect) to retrieve the original record payload alongside the error details. This approach lets you continue processing valid records while preserving the failed ones for later analysis and reprocessing.
If you need deeper insight into pipeline behavior—for example, to trace the path of a specific record through multiple stages—you can enable trace mode in the configuration. Trace mode adds a unique identifier to each record at ingestion and logs every stage transition that record goes through. This is particularly useful for understanding timing issues or verifying that transformation logic produces the expected output at each step. Trace mode has a noticeable performance overhead and should not be left enabled in production, but it is invaluable during development and when investigating issues that are difficult to reproduce in a controlled test environment.