celery/celery · error · ImproperlyConfigured

The configured path for the file-system backend does not wor

Error message

The configured path for the file-system backend does not
work correctly, please make sure that it exists and has
the correct permissions.

What it means

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.

Source

Thrown at celery/backends/filesystem.py:75

        kwargs = {} if not kwargs else kwargs
        return super().__reduce__(args, {**kwargs, 'url': self.url})

    def _find_path(self, url):
        if not url:
            raise ImproperlyConfigured(E_NO_PATH_SET)
        if url.startswith('file://localhost/'):
            return url[16:]
        if url.startswith('file://'):
            return url[7:]
        raise ImproperlyConfigured(E_PATH_NON_CONFORMING_SCHEME)

    def _do_directory_test(self, key):
        try:
            self.set(key, b'test value')
            assert self.get(key) == b'test value'
            self.delete(key)
        except OSError:
            raise ImproperlyConfigured(E_PATH_INVALID)

    def _filename(self, key):
        return self.sep.join((self.path, key))

    def get(self, key):
        try:
            with self.open(self._filename(key), 'rb') as infile:
                return infile.read()
        except FileNotFoundError:
            pass

    def set(self, key, value):
        with self.open(self._filename(key), 'wb') as outfile:
            outfile.write(ensure_bytes(value))

    def mget(self, keys):
        for key in keys:
            yield self.get(key)

View on GitHub (pinned to 571efe8120)

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.

Example fix

# before
result_backend = 'file:///var/lib/celery/results'
# dir missing -> ImproperlyConfigured(E_PATH_INVALID)

# after
# in Dockerfile / entrypoint
mkdir -p /var/lib/celery/results && chown -R celery:celery /var/lib/celery
result_backend = 'file:///var/lib/celery/results'

Defensive patterns

Strategy: validation

Validate before calling

import os

path = url[len('file://localhost/'):] if url.startswith('file://localhost/') else url[len('file://'):]
os.makedirs(path, exist_ok=True)
probe = os.path.join(path, '.probe')
with open(probe, 'w') as f: f.write('x')
os.unlink(probe)

Type guard

import os

def is_writable_dir(url: str) -> bool:
    try:
        path = url[7:] if url.startswith('file://') else url
        return os.path.isdir(path) and os.access(path, os.W_OK | os.R_OK)
    except Exception:
        return False

Try / catch

from celery.exceptions import ImproperlyConfigured

try:
    FilesystemBackend(app=app, url=url)
except ImproperlyConfigured as exc:
    if 'work correctly' in str(exc) or 'permissions' in str(exc):
        log.error('Create and chmod the results directory for the worker user')
    raise

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of celery/celery@571efe8120 (2026-08-04). Data as JSON: /data/errors/5fb888db913dbaf3.json. Report an issue: GitHub.