{"record":{"id":"320ab0208da50156","repo":"flipped-aurora/gin-vue-admin","slug":"function-os-create-failed-err","errorCode":null,"errorMessage":"function os.Create() failed, err:","messagePattern":"function os\\.Create\\(\\) failed, err:","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"server/utils/upload/local.go","lineNumber":62,"sourceCode":"\t\tlogger.WithCtx(ctx).Mod(\"upload\").Err(mkdirErr).Error(\"function os.MkdirAll() failed\")\n\t\treturn \"\", \"\", errors.New(\"function os.MkdirAll() failed, err:\" + mkdirErr.Error())\n\t}\n\t// 拼接路径和文件名\n\tp := global.GVA_CONFIG.Local.StorePath + \"/\" + filename\n\tfilepath := global.GVA_CONFIG.Local.Path + \"/\" + filename\n\n\tf, openError := file.Open() // 读取文件\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\tdefer f.Close() // 创建文件 defer 关闭\n\n\tout, createErr := os.Create(p)\n\tif createErr != nil {\n\t\tlogger.WithCtx(ctx).Mod(\"upload\").Err(createErr).Error(\"function os.Create() failed\")\n\n\t\treturn \"\", \"\", errors.New(\"function os.Create() failed, err:\" + createErr.Error())\n\t}\n\tdefer out.Close() // 创建文件 defer 关闭\n\n\t_, copyErr := io.Copy(out, f) // 传输（拷贝）文件\n\tif copyErr != nil {\n\t\tlogger.WithCtx(ctx).Mod(\"upload\").Err(copyErr).Error(\"function io.Copy() failed\")\n\t\treturn \"\", \"\", errors.New(\"function io.Copy() failed, err:\" + copyErr.Error())\n\t}\n\treturn filepath, filename, nil\n}\n\n//@author: [piexlmax](https://github.com/piexlmax)\n//@author: [ccfish86](https://github.com/ccfish86)\n//@author: [SliverHorn](https://github.com/SliverHorn)\n//@object: *Local\n//@function: DeleteFile\n//@description: 删除文件\n//@param: key string","sourceCodeStart":44,"sourceCodeEnd":80,"githubUrl":"https://github.com/flipped-aurora/gin-vue-admin/blob/3136500ef380842b0eb6c4daa87c3f8a47fcf9e0/server/utils/upload/local.go#L44-L80","documentation":"This error is returned by Local.UploadFile when os.Create() fails to create the destination file under the configured local store path (global.GVA_CONFIG.Local.StorePath). os.Create fails when the path is unwritable, a parent directory component is missing (though MkdirAll runs first), or the target exists as a directory. The underlying OS error is appended to the message.","triggerScenarios":"Calling UploadFile on a Local upload adapter when the OS cannot create StorePath/<md5>_<timestamp><ext>: read-only filesystem or volume, insufficient file permissions for the process user, StorePath points at an existing directory with the generated filename, or disk full (ENOSPC).","commonSituations":"Docker containers running as non-root with the uploads volume owned by root; store path configured to a Windows drive letter that doesn't exist; disk quota exhaustion; deploying with a relative StorePath that resolves against an unexpected working directory.","solutions":["Check the appended OS error (e.g. permission denied vs no such file) and fix filesystem permissions: chown/chmod the StorePath directory so the server process can write.","Verify local.store-path in config.yaml points to an existing writable absolute path and that os.MkdirAll on it succeeds.","Check disk space (df -h) and quota; free space if ENOSPC.","If running in Docker/K8s, confirm the volume is mounted read-write and the container user matches the volume owner."],"exampleFix":"// before (config.yaml)\nlocal:\n  store-path: /data/uploads   # directory owned by root, process runs as app user\n// after\n# shell\nsudo chown -R appuser:appuser /data/uploads && chmod 755 /data/uploads","handlingStrategy":"validation","validationCode":"func ensureStoreWritable(storePath string) error {\n    if err := os.MkdirAll(storePath, 0o755); err != nil {\n        return fmt.Errorf(\"store dir unavailable: %w\", err)\n    }\n    probe := filepath.Join(storePath, \".write-probe\")\n    if err := os.WriteFile(probe, []byte(\"ok\"), 0o644); err != nil {\n        return fmt.Errorf(\"store dir not writable: %w\", err)\n    }\n    _ = os.Remove(probe)\n    return nil\n}\n// call at startup: ensureStoreWritable(global.GVA_CONFIG.Local.StorePath)","typeGuard":null,"tryCatchPattern":"filePath, filename, err := local.UploadFile(ctx, fileHeader)\nif err != nil {\n    if strings.HasPrefix(err.Error(), \"function os.Create() failed\") {\n        // surface a 500 with admin hint: check store-path permissions/disk\n    }\n    return err\n}","preventionTips":["Run a startup health check that creates and removes a probe file in StorePath.","Run the server process as a dedicated user that owns the uploads directory.","Monitor disk usage and alert before ENOSPC.","Use absolute paths for local.store-path in every environment's config."],"tags":["filesystem","file-upload","permissions","go"],"backgroundTag":"file-create-permission-denied","analyzedSha":"3136500ef380842b0eb6c4daa87c3f8a47fcf9e0","analyzedAt":"2026-08-31T13:50:02.721Z","schemaVersion":2},"datasetVersion":"2026-08-31T19:17:28.585Z"}