{"record":{"id":"b3004e99a822f8c9","repo":"flipped-aurora/gin-vue-admin","slug":"minio-client-err","errorCode":null,"errorMessage":"minio client 初始化失败, err:","messagePattern":"minio client 初始化失败, err:","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/utils/upload/minio_oss.go","lineNumber":46,"sourceCode":"func newMinioClient() (*minio.Client, error) {\n\tcfg := global.GVA_CONFIG.Minio\n\tendpoint := strings.TrimPrefix(strings.TrimPrefix(cfg.Endpoint, \"https://\"), \"http://\")\n\n\tminioClient, err := minio.New(endpoint, &minio.Options{\n\t\tCreds:  credentials.NewStaticV4(cfg.AccessKeyId, cfg.AccessKeySecret, \"\"),\n\t\tSecure: cfg.UseSSL, // Set to true if using https\n\t})\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\treturn minioClient, nil\n}\n\nfunc (m *Minio) UploadFile(ctx context.Context, file *multipart.FileHeader) (filePathres, key string, uploadErr error) {\n\tclient, err := newMinioClient()\n\tif err != nil {\n\t\tlogger.WithCtx(ctx).Mod(\"upload\").Err(err).Error(\"minio client 初始化失败\")\n\t\treturn \"\", \"\", errors.New(\"minio client 初始化失败, err:\" + err.Error())\n\t}\n\n\tf, openError := file.Open()\n\t// mutipart.File to os.File\n\tif openError != nil {\n\t\tlogger.WithCtx(ctx).Mod(\"upload\").Err(openError).Error(\"function file.Open() Failed\")\n\t\treturn \"\", \"\", errors.New(\"function file.Open() Failed, err:\" + openError.Error())\n\t}\n\n\tfilecontent := bytes.Buffer{}\n\t_, err = io.Copy(&filecontent, f)\n\tif err != nil {\n\t\tlogger.WithCtx(ctx).Mod(\"upload\").Err(err).Error(\"读取文件失败\")\n\t\treturn \"\", \"\", errors.New(\"读取文件失败, err:\" + err.Error())\n\t}\n\tf.Close() // 创建文件 defer 关闭\n\n\t// 对文件名进行加密存储","sourceCodeStart":28,"sourceCodeEnd":64,"githubUrl":"https://github.com/flipped-aurora/gin-vue-admin/blob/3136500ef380842b0eb6c4daa87c3f8a47fcf9e0/server/utils/upload/minio_oss.go#L28-L64","documentation":"This error is returned by Minio.UploadFile when newMinioClient() fails to construct the MinIO client. Initialization fails on invalid endpoint format, unresolvable/invalid address, or TLS/credential setup errors reported by the minio-go library. The underlying error is appended after the 'minio client 初始化失败, err:' prefix.","triggerScenarios":"UploadFile called with a misconfigured MinIO endpoint in config (missing scheme handling, malformed host:port, empty endpoint), DNS failure resolving the MinIO host, or invalid TLS options passed to minio.New.","commonSituations":"minio.address configured as 'http://host:9000' or with a trailing slash instead of plain host:port; typo in hostname; MinIO not yet started when the app boots and receives its first upload; docker-compose service name not resolvable from the app container.","solutions":["Check the appended error and fix local.minio config: endpoint must be host:port (e.g. '127.0.0.1:9000'), with use-ssl controlling TLS rather than a URL scheme.","Verify the MinIO host resolves and is reachable: ping/nc to the endpoint from the app container.","Ensure MinIO container/service is running and the port is published/reachable from the app.","Validate access-key/secret-key are set correctly (invalid creds usually surface later, but empty values can break client setup)."],"exampleFix":"// before (config.yaml)\nminio:\n  address: http://minio:9000   # scheme not allowed here\n// after\nminio:\n  address: minio:9000\n  use-ssl: false\n  access-key-id: minioadmin\n  secret-access-key: minioadmin","handlingStrategy":"validation","validationCode":"func validateMinioConfig(cfg config.Minio) error {\n    if cfg.Address == \"\" {\n        return errors.New(\"minio address is empty\")\n    }\n    if strings.Contains(cfg.Address, \"://\") {\n        return fmt.Errorf(\"minio address %q must be host:port without scheme\", cfg.Address)\n    }\n    host, port, err := net.SplitHostPort(cfg.Address)\n    if err != nil || host == \"\" || port == \"\" {\n        return fmt.Errorf(\"minio address %q is not host:port\", cfg.Address)\n    }\n    if _, err := net.LookupHost(host); err != nil {\n        return fmt.Errorf(\"minio host %q does not resolve: %w\", host, err)\n    }\n    return nil\n}","typeGuard":null,"tryCatchPattern":"filePath, key, err := minioUploader.UploadFile(ctx, fileHeader)\nif err != nil {\n    if strings.HasPrefix(err.Error(), \"minio client 初始化失败\") {\n        // configuration/connectivity problem: fail fast, alert ops, do not retry blindly\n        return fmt.Errorf(\"storage unavailable, check minio config/connectivity: %w\", err)\n    }\n    return err\n}","preventionTips":["Keep endpoint as bare host:port in config; toggle TLS with the use-ssl flag.","Add a readiness check that constructs the client and buckets: bucketExists at startup.","Use docker-compose healthchecks/depends_on so MinIO is up before the app.","Pin MinIO hostnames resolvable inside the container network (service names, not localhost)."],"tags":["minio","configuration","object-storage","go"],"backgroundTag":"object-storage-client-init-failed","analyzedSha":"3136500ef380842b0eb6c4daa87c3f8a47fcf9e0","analyzedAt":"2026-08-31T13:50:02.721Z","schemaVersion":2},"datasetVersion":"2026-08-31T19:17:28.585Z"}