{"id":"5fb888db913dbaf3","repo":"celery/celery","slug":"the-configured-path-for-the-file-system-backend-do","errorCode":null,"errorMessage":"The configured path for the file-system backend does not\nwork correctly, please make sure that it exists and has\nthe correct permissions.","messagePattern":"The configured path for the file-system backend does not\nwork correctly, please make sure that it exists and has\nthe correct permissions\\.","errorType":"exception","errorClass":"ImproperlyConfigured","httpStatus":null,"severity":"error","filePath":"celery/backends/filesystem.py","lineNumber":75,"sourceCode":"        kwargs = {} if not kwargs else kwargs\n        return super().__reduce__(args, {**kwargs, 'url': self.url})\n\n    def _find_path(self, url):\n        if not url:\n            raise ImproperlyConfigured(E_NO_PATH_SET)\n        if url.startswith('file://localhost/'):\n            return url[16:]\n        if url.startswith('file://'):\n            return url[7:]\n        raise ImproperlyConfigured(E_PATH_NON_CONFORMING_SCHEME)\n\n    def _do_directory_test(self, key):\n        try:\n            self.set(key, b'test value')\n            assert self.get(key) == b'test value'\n            self.delete(key)\n        except OSError:\n            raise ImproperlyConfigured(E_PATH_INVALID)\n\n    def _filename(self, key):\n        return self.sep.join((self.path, key))\n\n    def get(self, key):\n        try:\n            with self.open(self._filename(key), 'rb') as infile:\n                return infile.read()\n        except FileNotFoundError:\n            pass\n\n    def set(self, key, value):\n        with self.open(self._filename(key), 'wb') as outfile:\n            outfile.write(ensure_bytes(value))\n\n    def mget(self, keys):\n        for key in keys:\n            yield self.get(key)","sourceCodeStart":57,"sourceCodeEnd":93,"githubUrl":"https://github.com/celery/celery/blob/571efe81202341310b6257304980ba7898ab0f60/celery/backends/filesystem.py#L57-L93","documentation":"After resolving the path, FilesystemBackend._do_directory_test writes, reads back, and deletes a probe file; if any step raises OSError it raises ImproperlyConfigured(E_PATH_INVALID). This catches missing directories and permission problems at backend init rather than silently corrupting results.","triggerScenarios":"Pointing 'file:///var/lib/celery/results' at a directory that does not exist, or where the Celery user lacks read/write/unlink permission. The OSError at filesystem.py:74 is converted to ImproperlyConfigured.","commonSituations":"The results dir was never created; running the worker as a user without ownership; read-only mounts in a container; SELinux/AppArmor denying writes; NFS mount not yet attached at worker start.","solutions":["Create the directory: mkdir -p /var/lib/celery/results and chown it to the Celery user.","Grant write+read+delete permissions (chmod or chown) for the worker process owner.","If read-only by design, switch to a different result backend.","Ensure network mounts are attached before the worker starts; use an init container/prestart hook to create the dir."],"exampleFix":"# before\nresult_backend = 'file:///var/lib/celery/results'\n# dir missing -> ImproperlyConfigured(E_PATH_INVALID)\n\n# after\n# in Dockerfile / entrypoint\nmkdir -p /var/lib/celery/results && chown -R celery:celery /var/lib/celery\nresult_backend = 'file:///var/lib/celery/results'","handlingStrategy":"validation","validationCode":"import os\n\npath = url[len('file://localhost/'):] if url.startswith('file://localhost/') else url[len('file://'):]\nos.makedirs(path, exist_ok=True)\nprobe = os.path.join(path, '.probe')\nwith open(probe, 'w') as f: f.write('x')\nos.unlink(probe)","typeGuard":"import os\n\ndef is_writable_dir(url: str) -> bool:\n    try:\n        path = url[7:] if url.startswith('file://') else url\n        return os.path.isdir(path) and os.access(path, os.W_OK | os.R_OK)\n    except Exception:\n        return False","tryCatchPattern":"from celery.exceptions import ImproperlyConfigured\n\ntry:\n    FilesystemBackend(app=app, url=url)\nexcept ImproperlyConfigured as exc:\n    if 'work correctly' in str(exc) or 'permissions' in str(exc):\n        log.error('Create and chmod the results directory for the worker user')\n    raise","preventionTips":["Pre-create results dirs in the image/entrypoint and chown to the worker user.","Mount a dedicated writable volume for results.","Run a write/delete probe in a prestart hook before the worker boots."],"tags":["celery","filesystem","storage","permissions","configuration","python"],"analyzedSha":"571efe81202341310b6257304980ba7898ab0f60","analyzedAt":"2026-08-04T20:17:20.567Z","schemaVersion":2}