Debug mode
Debug mode helps you inspect how Zep processes new episodes. When debug mode is enabled, Zep captures workflow logs for episodes processed during the active window. For Flex, Flex Plus, and Enterprise accounts, Zep also creates Ingestion Traces for selected extraction and resolution stages.
Use debug mode when an episode is pending, a graph update looks unexpected, or you need to understand why ingestion produced a specific result.
Debug logs can include data derived from your episode content and graph processing. Enable debug mode only when you need to troubleshoot, and review logs with the same care as other sensitive operational data.
Enable debug mode
Open Project Settings
In the Zep dashboard, open the project you want to debug, then go to Project Settings.
Debug mode is scoped to the project where it is enabled. It is time-limited and automatically turns off:
- Standard accounts: 60 minutes.
- Enterprise accounts: 24 hours.
Enabling debug mode again resets the active window.
Workflow logs
The Workflow tab in the episode logs dialog shows the ingestion workflow for that episode.
Workflow logs include:
- Episode status, start time, completion time, and top-level error details.
- Timestamped log entries with level and message.
- Step-by-step ingestion progress through graph construction.
- Errors and stack traces when a workflow step fails.
- Processing details that can help explain why a node, edge, or fact was created, changed, skipped, or failed.
Logs are available only for episodes processed while debug mode was active. Workflow logs are retained for a limited time: 12 hours by default and 7 days for Enterprise accounts.
Per-episode debug logs are not currently supported for batch ingestion operations.
Ingestion Traces
Ingestion Traces are available for Flex, Flex Plus, and Enterprise accounts. Turning on debug mode for an eligible project enables traces for eligible ingestion stages during the active window.
Ingestion Traces explain why selected LLM stages produced each decision during graph construction. Tracing is observational. It does not change the stage output or downstream ingestion.
The Ingestion Traces tab can include:
- Stage and prompt name, such as extraction or resolution.
- Validation status.
- Attempt count and error details when retries were needed.
- Inputs used by the ingestion stage.
- Stage output with each available decision explanation attached to its node, edge, or map entry.
- Trace metadata.
Ingestion Traces are most useful when an extracted entity, edge, or fact looks wrong. The trace connects each decision to the episode context, prior episodes, ontology, or deduplication candidates that informed it.
Zep retains Ingestion Traces for 30 days. The traces are not graph state, so graph deletion does not remove them before the retention period expires.
Troubleshooting
If an episode has no logs, check that debug mode was enabled before the episode was processed and that the log retention window has not expired.
If the Ingestion Traces tab is empty, one of the following is usually true:
- The account is not on a Flex, Flex Plus, or Enterprise plan.
- The episode was processed while debug mode was off.
- The episode did not run an ingestion stage that emits Ingestion Traces.
- Zep could not store the ingestion trace.
- The trace exhausted its retries. Ingestion continues with the original output, and Zep stores a failed trace when possible.
Debug mode does not change retrieval behavior or ingestion output. It enables workflow logs and, for eligible accounts, Ingestion Traces for new ingestion workflows.