{"record":{"id":"22816b51613eda96","repo":"iflytek/astron-agent","slug":"internal-server-error","errorCode":"INTERNAL_SERVER_ERROR","errorMessage":"INTERNAL_SERVER_ERROR","messagePattern":"INTERNAL_SERVER_ERROR","errorType":"error_code","errorClass":"BusinessException","httpStatus":500,"severity":"critical","filePath":"console/backend/commons/src/main/java/com/iflytek/astron/console/commons/util/S3ClientUtil.java","lineNumber":139,"sourceCode":"                    if (!isConcurrentBucketCreation(exception)) {\n                        throw exception;\n                    }\n                    log.info(\"S3 bucket was created concurrently: {}\", defaultBucket);\n                }\n            } else {\n                log.info(\"S3 bucket already exists: {}\", defaultBucket);\n            }\n\n            reconcileBucketPolicy(defaultBucket, enablePublicRead);\n        } catch (ErrorResponseException | InsufficientDataException | InternalException | InvalidKeyException\n                | InvalidResponseException | IOException | NoSuchAlgorithmException | ServerException\n                | XmlParserException e) {\n            log.error(\n                    \"Failed to check/create/configure S3 bucket '{}' (errorType={}, errorCode={})\",\n                    defaultBucket,\n                    exceptionType(e),\n                    safeS3ErrorCode(e));\n            throw new BusinessException(ResponseEnum.INTERNAL_SERVER_ERROR);\n        }\n    }\n\n    /**\n     * Validate required configuration parameters.\n     */\n    private void validateConfiguration() {\n        if (endpoint == null || endpoint.trim().isEmpty()) {\n            log.error(\"S3 endpoint is not configured\");\n            throw new BusinessException(ResponseEnum.INTERNAL_SERVER_ERROR);\n        }\n        if (remoteEndpoint == null || remoteEndpoint.trim().isEmpty()) {\n            log.error(\"S3 remoteEndpoint is not configured\");\n            throw new BusinessException(ResponseEnum.INTERNAL_SERVER_ERROR);\n        }\n        if (accessKey == null\n                || accessKey.trim().isEmpty()\n                || LEGACY_PLACEHOLDER_ACCESS_KEY.equals(accessKey.trim())) {","sourceCodeStart":121,"sourceCodeEnd":157,"githubUrl":"https://github.com/iflytek/astron-agent/blob/5e758547a83371a5a4b29dadf4ac03e8dd527635/console/backend/commons/src/main/java/com/iflytek/astron/console/commons/util/S3ClientUtil.java#L121-L157","documentation":"S3ClientUtil.init ensures the configured S3/MinIO bucket exists and is correctly configured (create, privacy policy). When any S3 SDK operation fails (bucket check/create/policy, or XML parsing of the response), the error is logged with errorType/errorCode and rethrown as a generic BusinessException(INTERNAL_SERVER_ERROR) — the real cause is only in the server log.","triggerScenarios":"Bean initialization against an unreachable endpoint, wrong credentials, a missing bucket the client cannot create, a policy document MinIO rejects, or a malformed XML response (XmlParserException).","commonSituations":"MinIO/S3 not started or wrong endpoint/port in docker-compose; incorrect access/secret keys; bucket name conflicts or insufficient permissions; MinIO version rejecting the enforced privacy policy; network/DNS issues between services.","solutions":["Check the service log line 'Failed to check/create/configure S3 bucket' for the underlying errorType/errorCode","Verify S3 endpoint, accessKey, secretKey and bucket config (env/properties) and that MinIO is reachable (curl the endpoint)","Confirm credentials have s3:CreateBucket/PutBucketPolicy permissions, or pre-create the bucket","Retry startup after fixing infra; the util intentionally maps all SDK failures to INTERNAL_SERVER_ERROR"],"exampleFix":"// before\n# application.yml\ns3.endpoint: http://minio:9001  # wrong port, connection fails at init\n// after\ns3.endpoint: http://minio:9000  # match the actual MinIO API port","handlingStrategy":"try-catch","validationCode":"boolean cfgOk = endpoint != null && !endpoint.isBlank() && accessKey != null && secretKey != null && defaultBucket != null;\nboolean reachable = cfgOk && java.net.InetAddress.getByName(java.net.URI.create(endpoint).getHost()).isReachable(3000);","typeGuard":null,"tryCatchPattern":"try { s3ClientUtil.init(); } catch (BusinessException e) { log.error(\"S3 init failed — check endpoint/credentials/bucket and server log for errorType/errorCode\", e); throw new IllegalStateException(\"Object storage unavailable\", e); }","preventionTips":["Health-check MinIO/S3 connectivity in CI and readiness probes before the app bean initializes","Pin MinIO/S3 SDK versions compatible with your server; verify the bucket policy is MinIO-supported","Use pre-created buckets with correct permissions rather than relying on init to create them","Surface the underlying SDK error code from the log, not just the generic 500"],"tags":["java","minio","s3","init","configuration"],"backgroundTag":"module-init-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"}