home-assistant/core · error · BackupReaderWriterError

Failed to create dir {tar_file_path.parent}: {err} ({err.__c

Error message

Failed to create dir {tar_file_path.parent}: {err} ({err.__class__.__name__})

What it means

BackupReaderWriterError raised when creating the backup destination directory (make_backup_dir on tar_file_path.parent) fails with an OSError. The backup manager could not create the directory that should hold the .tar file, so nothing can be written.

Source

Thrown at homeassistant/components/backup/manager.py:1907

                raise BackupManagerExceptionGroup(
                    f"Multiple errors when creating backup: {unhandled_exc}, {err}",
                    [unhandled_exc, err],
                ) from None

    def _mkdir_and_generate_backup_contents(
        self,
        backup_data: dict[str, Any],
        database_included: bool,
        password: str | None,
        tar_file_path: Path | None,
    ) -> tuple[Path, int]:
        """Generate backup contents and return the size."""
        if not tar_file_path:
            tar_file_path = self.temp_backup_dir / f"{backup_data['slug']}.tar"
        try:
            make_backup_dir(tar_file_path.parent)
        except OSError as err:
            raise BackupReaderWriterError(
                f"Failed to create dir {tar_file_path.parent}: "
                f"{err} ({err.__class__.__name__})"
            ) from err

        excludes = EXCLUDE_FROM_BACKUP
        if not database_included:
            excludes = excludes + EXCLUDE_DATABASE_FROM_BACKUP

        def is_excluded_by_filter(path: PurePath) -> bool:
            """Filter to filter excludes."""

            for exclude in excludes:
                # The home assistant core configuration directory is added as "data"
                # in the tar file, so we need to prefix that path to the filters.
                if not path.full_match(f"data/{exclude}"):
                    continue
                LOGGER.debug("Ignoring %s because of %s", path, exclude)
                return True

View on GitHub (pinned to 58a3fdb3ea)

Solutions

1. Check permissions/ownership of the backup and temp directories for the user HA runs as (e.g. chown, or fix the Docker volume mount read-only flag)
2. Verify the target filesystem is mounted and writable (touch a file in the directory as the HA user)
3. Free disk space / raise the quota
4. If using a custom local agent path, confirm the path exists and is writable

Example fix

# before: read-only or wrong-owner backup dir
$ ls -ld /config/backups  # drwxr-xr-x root root
# after
$ chown -R homeassistant:homeassistant /config/backups
$ chmod u+w /config/backups

import os
backup_dir = str(tar_file_path.parent)
assert os.path.isdir(backup_dir) and os.access(backup_dir, os.W_OK), f"backup dir not writable: {backup_dir}"

try:
    make_backup_dir(path.parent)
except OSError as err:
    raise BackupReaderWriterError(f"cannot create {path.parent}: {err}") from err

When it happens

Trigger: OSError (PermissionError, ReadOnlyFileSystemError, FileNotFoundError on a missing parent, disk issues) from make_backup_dir for the backup temp/output directory (default: the local backup dir under config, or temp_backup_dir).

Common situations: Backup directory on a read-only mount; container user lacks write permission on /config/backups or the temp dir; configured local agent path points to an unmounted/unplugged USB drive; disk full or quota exceeded.

Related errors

• You need at least Home Assistant version {backup_meta_versio
• Unauthorized
• Failed during {func.__name__}
• Failed to upload backup
• Backup {backup_id} not found

AI-assisted analysis of home-assistant/core@58a3fdb3ea (2026-08-14). Data as JSON: /api/errors/87b8dace83349579. Report an issue: GitHub.