{"record":{"id":"215c5e3156cde82f","repo":"iflytek/astron-agent","slug":"8517-database-table-field-illegal","errorCode":"8517","errorMessage":"database.table.field.illegal","messagePattern":"database\\.table\\.field\\.illegal","errorType":"error_code","errorClass":"BusinessException","httpStatus":null,"severity":"error","filePath":"console/backend/toolkit/src/main/java/com/iflytek/astron/console/toolkit/service/database/DatabaseService.java","lineNumber":715,"sourceCode":"                if ((i + 1) % BATCH == 0) {\n                    // Thread.yield(); // Optional\n                }\n            }\n        } catch (Exception ex) {\n            log.error(\"Table operation failed, params={}\", JSONObject.toJSONString(dbTableOperateDto), ex);\n            throw new BusinessException(ResponseEnum.DATABASE_TABLE_OPERATION_FAILED);\n        }\n    }\n\n    private void validateParams(Map<String, Object> params, List<DbTableField> fields, Integer operateType) {\n        // 1. Get all table field names\n        Set<String> fieldNames = fields.stream().map(DbTableField::getName).collect(Collectors.toSet());\n\n        // 2. Validate illegal fields\n        for (String paramKey : params.keySet()) {\n            if (!fieldNames.contains(paramKey)) {\n                log.error(\"Illegal field: \" + paramKey);\n                throw new BusinessException(ResponseEnum.DATABASE_TABLE_FIELD_ILLEGAL);\n            }\n        }\n\n        // 3. Validate required fields\n        for (DbTableField field : fields) {\n            // Skip system field validation (for insert operations)\n            if (operateType.equals(DBOperateEnum.INSERT.getCode()) && Arrays.asList(SYSTEM_FIELDS).contains(field.getName())) {\n                continue;\n            }\n            if (operateType.equals(DBOperateEnum.DELETE.getCode()) || operateType.equals(DBOperateEnum.UPDATE.getCode())) {\n                // For delete and update operations, uuid and create_time are not validated\n                if (Arrays.asList(\"uuid\", \"create_time\").contains(field.getName())) {\n                    continue;\n                }\n            }\n            // Validate required fields without default values\n            if (Boolean.TRUE.equals(field.getIsRequired()) && field.getDefaultValue() == null && !params.containsKey(field.getName())) {\n                log.error(\"Missing required field: \" + field.getName());","sourceCodeStart":697,"sourceCodeEnd":733,"githubUrl":"https://github.com/iflytek/astron-agent/blob/5e758547a83371a5a4b29dadf4ac03e8dd527635/console/backend/toolkit/src/main/java/com/iflytek/astron/console/toolkit/service/database/DatabaseService.java#L697-L733","documentation":"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.","triggerScenarios":"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).","commonSituations":"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).","solutions":["Read the log 'Illegal field: <key>' to identify the offending key.","Remove the unknown key from the request params or correct its spelling.","Fetch current field metadata (GET table detail) and rebuild the payload to match exactly.","If the field is genuinely needed, add it to the table schema first, then resubmit."],"exampleFix":"// before\nparams.put(\"user_name\", \"alice\"); // table field is actually \"username\"\ndatabaseService.operateTableData(dto);\n// after\nif (!fieldNames.contains(\"username\")) throw new IllegalStateException(\"check schema\");\nparams.put(\"username\", \"alice\");\ndatabaseService.operateTableData(dto);","handlingStrategy":"validation","validationCode":"Set<String> fieldNames = fields.stream().map(DbTableField::getName).collect(Collectors.toSet());\nList<String> illegal = params.keySet().stream().filter(k -> !fieldNames.contains(k)).collect(Collectors.toList());\nif (!illegal.isEmpty()) throw new IllegalArgumentException(\"unknown fields: \" + illegal);","typeGuard":"boolean isKnownField(String key, Set<String> fieldNames) { return key != null && fieldNames.contains(key); }","tryCatchPattern":"try {\n    databaseService.operateTableData(dto);\n} catch (BusinessException ex) {\n    if (\"database.table.field.illegal\".equals(ex.getMessage())) {\n        log.warn(\"payload contains fields not in table schema; refresh schema and retry\");\n    }\n    throw ex;\n}","preventionTips":["Fetch fresh field metadata before building payloads","Strip non-schema keys (timestamps, client-side extras) before submit","Keep client forms generated from table metadata, not hardcoded"],"tags":["validation","schema","fields"],"backgroundTag":"schema-validation-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"}