{"record":{"id":"3e44c7fa39c8dce1","repo":"iflytek/astron-agent","slug":"eng-run-error-add-history-method-failed-to-add-llm-history-e","errorCode":"ENG_RUN_ERROR","errorMessage":"add_history method failed to add LLM history; {e}","messagePattern":"add_history method failed to add LLM history; (.+?)","errorType":"error_code","errorClass":"CustomException","httpStatus":null,"severity":"error","filePath":"core/workflow/service/history_service.py","lineNumber":77,"sourceCode":"            ):\n                raw_answer[\"content\"] = ra_content[: int(DB_ROW_LENGTH_LIMIT)]\n\n            # Serialize question and answer data to JSON strings\n            question_str = json.dumps(raw_question, ensure_ascii=False)\n            answer_str = json.dumps(raw_answer, ensure_ascii=False)\n\n            # Create and persist history record\n            db_history = History(\n                flow_id=flow_id,\n                node_id=node_id,\n                uid=uid,\n                raw_question=question_str,\n                raw_answer=answer_str,\n                chat_id=chat_id,\n            )\n            session.add(db_history)\n    except Exception as e:\n        raise CustomException(\n            CodeEnum.ENG_RUN_ERROR,\n            err_msg=f\"add_history method failed to add LLM history; {e}\",\n            cause_error=f\"err code : {CodeEnum.ENG_RUN_ERROR.code}. \"\n            f\"message: add_history method failed to add LLM history; {e}\",\n        ) from e\n\n\ndef get_history(\n    flow_id: str,\n    uid: str,\n    node_max_token: Optional[Dict[str, int]] = None,\n    history_size: int = MAX_HISTORY_SIZE,\n) -> List[Dict]:\n    \"\"\"Retrieve conversation history for a specific flow and user.\n\n    :param flow_id: Unique identifier for the workflow flow\n    :param uid: User identifier\n    :param node_max_token: Optional dictionary mapping node IDs to token limits","sourceCodeStart":59,"sourceCodeEnd":95,"githubUrl":"https://github.com/iflytek/astron-agent/blob/5e758547a83371a5a4b29dadf4ac03e8dd527635/core/workflow/service/history_service.py#L59-L95","documentation":"ENG_RUN_ERROR wrapper raised in history_service.add_history when any exception occurs while persisting the LLM Q/A pair (building ChatHistory model and session.add). The original exception is chained with `from e` and echoed into err_msg and cause_error.","triggerScenarios":"Database session errors during add_history: connection failure, transaction rollback from a prior error, constraint violation, or serialization failure of question_str/answer_str into the db_history model.","commonSituations":"DB connection pool exhausted or database down, session left in a failed state from an earlier flush, history table schema mismatch after migration, oversized answer text exceeding column limits.","solutions":["Inspect cause_error / chained exception `e` for the root DB error","Verify database connectivity and session health before/around add_history","Check the chat history table schema and column size limits against the payload","Rollback and retry the session transaction after a failed flush"],"exampleFix":"# before\nsession.add(db_history)  # session in failed state\n# after\nsession.rollback()\nsession.add(db_history)\nsession.commit()","handlingStrategy":"try-catch","validationCode":"# verify DB connectivity before persisting history\nsession.execute(text('SELECT 1'))","typeGuard":null,"tryCatchPattern":"try:\n    await history_service.add_history(...)\nexcept CustomException as e:\n    if e.err_code == CodeEnum.ENG_RUN_ERROR and 'add_history' in e.err_msg:\n        log.error('history persistence failed: %s', e.cause_error)\n        session.rollback()  # do not fail the chat run for history write issues\n    else:\n        raise","preventionTips":["Rollback and refresh sessions after failed flushes","Monitor DB connection pool health","Keep history table schema/migrations in sync with the model","Truncate or compress oversized answers exceeding column limits"],"tags":["database","history","persistence"],"backgroundTag":"database-write-failed","analyzedSha":"5e758547a83371a5a4b29dadf4ac03e8dd527635","analyzedAt":"2026-09-12T08:03:51.356Z","contentChangedAt":"2026-09-12T08:03:51.356Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}