iflytek/astron-agent · error · BusinessException

8517

8517

Error message

database.table.field.illegal

What it means

Thrown by the private validateParams helper of DatabaseService when a request supplies a parameter key that does not match any declared table field name. Code 8517, message 'database.table.field.illegal'. This is a strict allowlist check: every key in params must exist in the DbTableField metadata.

Solutions

1. Read the log 'Illegal field: <key>' to identify the offending key.
2. Remove the unknown key from the request params or correct its spelling.
3. Fetch current field metadata (GET table detail) and rebuild the payload to match exactly.
4. If the field is genuinely needed, add it to the table schema first, then resubmit.

Example fix

// before
params.put("user_name", "alice"); // table field is actually "username"
databaseService.operateTableData(dto);
// after
if (!fieldNames.contains("username")) throw new IllegalStateException("check schema");
params.put("username", "alice");
databaseService.operateTableData(dto);

Set<String> fieldNames = fields.stream().map(DbTableField::getName).collect(Collectors.toSet());
List<String> illegal = params.keySet().stream().filter(k -> !fieldNames.contains(k)).collect(Collectors.toList());
if (!illegal.isEmpty()) throw new IllegalArgumentException("unknown fields: " + illegal);

boolean isKnownField(String key, Set<String> fieldNames) { return key != null && fieldNames.contains(key); }

try {
    databaseService.operateTableData(dto);
} catch (BusinessException ex) {
    if ("database.table.field.illegal".equals(ex.getMessage())) {
        log.warn("payload contains fields not in table schema; refresh schema and retry");
    }
    throw ex;
}

When it happens

Trigger: operateTableData or importTableData receives a params map containing a key not present in the table's field list (e.g. typo 'naem' instead of 'name', a system field like 'id' submitted on insert, or a field removed after the client was built).

Common situations: Frontend/form sends stale fields after the table schema was edited; API consumers guessing field names; extra JSON fields from serialization (e.g. 'createdAt' auto-added by client SDK).

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Header mismatch! Expected headers: , Actual headers:
• 8518
• Invalid RID value provided.
• User UID cannot be null
• User ID cannot be null

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

Appendix: source

Thrown at console/backend/toolkit/src/main/java/com/iflytek/astron/console/toolkit/service/database/DatabaseService.java:715

                if ((i + 1) % BATCH == 0) {
                    // Thread.yield(); // Optional
                }
            }
        } catch (Exception ex) {
            log.error("Table operation failed, params={}", JSONObject.toJSONString(dbTableOperateDto), ex);
            throw new BusinessException(ResponseEnum.DATABASE_TABLE_OPERATION_FAILED);
        }
    }

    private void validateParams(Map<String, Object> params, List<DbTableField> fields, Integer operateType) {
        // 1. Get all table field names
        Set<String> fieldNames = fields.stream().map(DbTableField::getName).collect(Collectors.toSet());

        // 2. Validate illegal fields
        for (String paramKey : params.keySet()) {
            if (!fieldNames.contains(paramKey)) {
                log.error("Illegal field: " + paramKey);
                throw new BusinessException(ResponseEnum.DATABASE_TABLE_FIELD_ILLEGAL);
            }
        }

        // 3. Validate required fields
        for (DbTableField field : fields) {
            // Skip system field validation (for insert operations)
            if (operateType.equals(DBOperateEnum.INSERT.getCode()) && Arrays.asList(SYSTEM_FIELDS).contains(field.getName())) {
                continue;
            }
            if (operateType.equals(DBOperateEnum.DELETE.getCode()) || operateType.equals(DBOperateEnum.UPDATE.getCode())) {
                // For delete and update operations, uuid and create_time are not validated
                if (Arrays.asList("uuid", "create_time").contains(field.getName())) {
                    continue;
                }
            }
            // Validate required fields without default values
            if (Boolean.TRUE.equals(field.getIsRequired()) && field.getDefaultValue() == null && !params.containsKey(field.getName())) {
                log.error("Missing required field: " + field.getName());

View on GitHub (pinned to 5e758547a8)