iflytek/astron-agent · error · CustomException

SQLParseError

SQLParseError

Error message

Missing binding parameters: {missing}

What it means

parse_and_exec_sql extracts named bind parameters (:name) from the SQL and compares them with the provided params dict. If any parameter has no value, it raises CustomException with code SQLParseError before touching the database, preventing an SQLAlchemy arg error.

Solutions

1. Add every missing key to the params dict before execution
2. Remove unused :placeholders from the SQL
3. Log param_names vs provided keys to find the omitted one

Example fix

// before
await parse_and_exec_sql(session, "UPDATE t SET a = :a WHERE id = :id", {"a": 1})
// after
await parse_and_exec_sql(session, "UPDATE t SET a = :a WHERE id = :id", {"a": 1, "id": 7})

from utils import extract_sql_params
required = extract_sql_params(sql)
missing = set(required) - set(params or {})
if missing:
    raise ValueError(f'provide bind params: {missing}')

try:
    await parse_and_exec_sql(session, sql, params)
except CustomException as e:
    if e.code == CodeEnum.SQLParseError.code:
        # inspect e.message for the missing set and re-issue with params
        ...
    raise

When it happens

Trigger: Calling _exec_dml_sql / _dml_split / _get_table_column_types with SQL containing :param placeholders but params omitting one or more of those names (e.g. None or partially filled dict).

Common situations: Template SQL edited by hand where a placeholder was added but the caller's param map was not updated; dynamic SQL builders that skip optional fields.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• PG_SQL_NODE_EXECUTION_ERROR
• Column names must be used in UPDATE SET clause
• Error creating table
• PG_SQL_PARAM_ERROR
• Something went wrong creating the database and tables.

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

Appendix: source

Thrown at core/memory/database/domain/entity/general.py:50

) -> Any:
    """
    Safely parse and execute SQL with automatic parameter binding.

    Args:
        session: SQLAlchemy AsyncSession
        sql: SQL statement with binding parameters (e.g., :username)
        params: Parameter dictionary, e.g., {"username": "alice"}

    Returns:
        SQL execution result
    Raises:
        MissingSQLParamsError: If there are missing binding parameters
    """
    param_names = extract_sql_params(sql)
    provided_keys = set(params or {})
    missing = param_names - provided_keys
    if missing:
        raise CustomException(
            err_code=CodeEnum.SQLParseError.code,
            err_msg=f"Missing binding parameters: {missing}",
        )

    return await session.execute(text(sql), params or {})


@retry_on_invalid_cached_statement(max_retries=3)
async def exec_sql_statement(session: AsyncSession, statement: str) -> Any:
    """Execute raw SQL statement

    Args:
        session: SQLAlchemy AsyncSession
        statement: SQL statement to execute

    Returns:
        SQL execution result
    """

View on GitHub (pinned to 5e758547a8)