iflytek/astron-agent · error · CustomException

ENG_RUN_ERROR

ENG_RUN_ERROR

Error message

add_history method failed to add LLM history; {e}

What it means

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.

Solutions

  1. Inspect cause_error / chained exception `e` for the root DB error
  2. Verify database connectivity and session health before/around add_history
  3. Check the chat history table schema and column size limits against the payload
  4. Rollback and retry the session transaction after a failed flush

Example fix

# before
session.add(db_history)  # session in failed state
# after
session.rollback()
session.add(db_history)
session.commit()
Defensive patterns

Strategy: try-catch

Validate before calling

# verify DB connectivity before persisting history
session.execute(text('SELECT 1'))

Try / catch

try:
    await history_service.add_history(...)
except CustomException as e:
    if e.err_code == CodeEnum.ENG_RUN_ERROR and 'add_history' in e.err_msg:
        log.error('history persistence failed: %s', e.cause_error)
        session.rollback()  # do not fail the chat run for history write issues
    else:
        raise

Prevention

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of iflytek/astron-agent@5e758547a8 (2026-09-12). Data as JSON: /api/errors/3e44c7fa39c8dce1. Report an issue: GitHub.

Appendix: source

Thrown at core/workflow/service/history_service.py:77

            ):
                raw_answer["content"] = ra_content[: int(DB_ROW_LENGTH_LIMIT)]

            # Serialize question and answer data to JSON strings
            question_str = json.dumps(raw_question, ensure_ascii=False)
            answer_str = json.dumps(raw_answer, ensure_ascii=False)

            # Create and persist history record
            db_history = History(
                flow_id=flow_id,
                node_id=node_id,
                uid=uid,
                raw_question=question_str,
                raw_answer=answer_str,
                chat_id=chat_id,
            )
            session.add(db_history)
    except Exception as e:
        raise CustomException(
            CodeEnum.ENG_RUN_ERROR,
            err_msg=f"add_history method failed to add LLM history; {e}",
            cause_error=f"err code : {CodeEnum.ENG_RUN_ERROR.code}. "
            f"message: add_history method failed to add LLM history; {e}",
        ) from e


def get_history(
    flow_id: str,
    uid: str,
    node_max_token: Optional[Dict[str, int]] = None,
    history_size: int = MAX_HISTORY_SIZE,
) -> List[Dict]:
    """Retrieve conversation history for a specific flow and user.

    :param flow_id: Unique identifier for the workflow flow
    :param uid: User identifier
    :param node_max_token: Optional dictionary mapping node IDs to token limits

View on GitHub (pinned to 5e758547a8)