{"record":{"id":"a66fd35e52e873b5","repo":"Tencent/WeKnora","slug":"storage-directory-not-accessible-w","errorCode":null,"errorMessage":"storage directory not accessible: %w","messagePattern":"storage directory not accessible: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/application/service/file/local.go","lineNumber":30,"sourceCode":"\n\t\"github.com/Tencent/WeKnora/internal/logger\"\n\t\"github.com/Tencent/WeKnora/internal/types/interfaces\"\n\tsecutils \"github.com/Tencent/WeKnora/internal/utils\"\n)\n\n// localFileService implements the FileService interface for local file system storage\ntype localFileService struct {\n\tbaseDir     string // Base directory for file storage\n\texternalURL string // External URL base for presigned URL generation (empty = return local:// paths)\n}\n\nconst localScheme = \"local://\"\n\n// CheckConnectivity verifies the local storage directory exists and is accessible.\nfunc (s *localFileService) CheckConnectivity(ctx context.Context) error {\n\tinfo, err := os.Stat(s.baseDir)\n\tif err != nil {\n\t\treturn fmt.Errorf(\"storage directory not accessible: %w\", err)\n\t}\n\tif !info.IsDir() {\n\t\treturn fmt.Errorf(\"storage path is not a directory: %s\", s.baseDir)\n\t}\n\treturn nil\n}\n\n// NewLocalFileService creates a new local file service instance.\n// externalURL is the externally-reachable base URL (e.g. \"https://weknora.example.com\");\n// when set, GetFileURL returns presigned HTTP URLs instead of local:// paths.\nfunc NewLocalFileService(baseDir, externalURL string) interfaces.FileService {\n\treturn &localFileService{\n\t\tbaseDir:     baseDir,\n\t\texternalURL: strings.TrimRight(externalURL, \"/\"),\n\t}\n}\n\n// SaveFile stores an uploaded file to the local file system","sourceCodeStart":12,"sourceCodeEnd":48,"githubUrl":"https://github.com/Tencent/WeKnora/blob/988cbb03305e055d8ebb7d46d9ac6cc0803cd074/internal/application/service/file/local.go#L12-L48","documentation":"localFileService.CheckConnectivity wraps os.Stat errors on s.baseDir with \"storage directory not accessible: %w\". It runs during health/connectivity checks to verify local file storage is usable. The wrapped error is almost always \"no such file or directory\" (ENOSQL dir missing) or \"permission denied\".","triggerScenarios":"os.Stat(baseDir) fails: the LOCAL_STORAGE_BASE_DIR directory doesn't exist, was deleted at runtime, is on an unmounted volume, or the process lacks read permission on it.","commonSituations":"Docker/K8s volume not mounted or mount path typo; fresh deployment where the data dir was never created; running container as non-root user while dir is root-owned; base dir on a detached PVC or host path that changed between restarts.","solutions":["Create the configured base directory: mkdir -p <LOCAL_STORAGE_BASE_DIR> (SaveFile creates subdirs, but the base itself must exist for connectivity checks).","Check the storage config/LOCAL_FILE_BASE_DIR env var points to the intended absolute path, not a typo or a path removed in a newer image.","Fix ownership/permissions so the service user can read/stat the directory (e.g. chown -R appuser:appuser /data/files, chmod 755).","In containerized deployments, verify the volume mount exists and is mounted (docker inspect / kubectl describe pod) and the PVC is Bound."],"exampleFix":"// before\n// LOCAL_FILE_BASE_DIR=/data/weknora/files  (dir missing in container)\n// after\n// Dockerfile / entrypoint\nRUN mkdir -p /data/weknora/files && chown -R appuser /data/weknora/files","handlingStrategy":"validation","validationCode":"info, err := os.Stat(baseDir)\nif err != nil || !info.IsDir() {\n\treturn fmt.Errorf(\"base dir %q unusable: %v\", baseDir, err)\n}","typeGuard":null,"tryCatchPattern":"if err := svc.CheckConnectivity(ctx); err != nil {\n\tlog.Fatalf(\"local storage unavailable: %v\", err) // fail fast at boot\n}","preventionTips":["Create the base directory in your Dockerfile/entrypoint before the app starts","Verify volume mounts in deploy manifests (PVC Bound, hostPath exists)","Run the service as a user with read access to the storage path","Call CheckConnectivity in readiness probes"],"tags":["filesystem","local-storage","configuration","deployment","go"],"backgroundTag":"storage-directory-not-accessible","analyzedSha":"988cbb03305e055d8ebb7d46d9ac6cc0803cd074","analyzedAt":"2026-09-02T14:41:08.344Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}