What causes "invalid backup path provided" in weaviate/weaviate?

Set the backups path to an absolute path (filepath.IsAbs must be true) in the module config/env.

invalid backup path provided

Error message

invalid backup path provided

What it means

This error wraps the failure of createBackupsDir during initBackupBackend, which runs when the backup-filesystem module is initialized at Weaviate startup with ENABLE_MODULES=backup-filesystem. The underlying cause is that the configured backups path could not be created or was rejected (e.g. relative path -> 'relative backup path provided'), so the module aborts initialization. It indicates a configuration or filesystem problem with the backups directory, not a problem with a specific backup request.

Source

Thrown at modules/backup-filesystem/backup.go:223

		metric.Add(float64(read))
	}
	return read, err
}

func (m *Module) SourceDataPath() string {
	return m.dataPath
}

func (m *Module) initBackupBackend(ctx context.Context, backupsPath string) error {
	if backupsPath == "" {
		return fmt.Errorf("empty backup path provided")
	}
	backupsPath = filepath.Clean(backupsPath)
	if !filepath.IsAbs(backupsPath) {
		return fmt.Errorf("relative backup path provided")
	}
	if err := m.createBackupsDir(backupsPath); err != nil {
		return errors.Wrap(err, "invalid backup path provided")
	}
	m.backupsPath = backupsPath

	return nil
}

func (m *Module) createBackupsDir(backupsPath string) error {
	if err := os.MkdirAll(backupsPath, os.ModePerm); err != nil {
		m.logger.WithField("module", m.Name()).
			WithField("action", "create_backups_dir").
			WithError(err).
			Errorf("failed creating backups directory %v", backupsPath)
		return backup.NewErrInternal(errors.Wrap(err, "make backups dir"))
	}
	return nil
}

View on GitHub (pinned to 75aa4b6d11)

Solutions

Set the backups path to an absolute path (filepath.IsAbs must be true) in the module config/env.
Read the wrapped inner error: 'relative backup path provided' means fix the config; otherwise fix the filesystem issue reported by createBackupsDir.
Pre-create the directory and give the weaviate process user ownership/write permission.
If the path lives on a mounted volume, verify the mount is ready and writable before starting Weaviate.

Example fix

// before
ENABLE_MODULES=backup-filesystem
PERSISTENCE_DATA_PATH=./data   # relative -> rejected
// after
ENABLE_MODULES=backup-filesystem
PERSISTENCE_DATA_PATH=/var/lib/weaviate/data

Defensive patterns

Strategy: validation

Validate before calling

p := filepath.Clean(os.Getenv("PERSISTENCE_DATA_PATH"))
if !filepath.IsAbs(p) {
    return fmt.Errorf("backup path must be absolute, got %q", p)
}
if _, err := os.Stat(p); err != nil {
    if err := os.MkdirAll(p, os.ModePerm); err != nil {
        return err
    }
}

Try / catch

if err := module.Init(params); err != nil {
    if strings.Contains(err.Error(), "relative backup path provided") {
        return fmt.Errorf("config: set an absolute PERSISTENCE_DATA_PATH: %w", err)
    }
    return err
}

Prevention

Always configure backups paths as absolute paths in env/config management.
Test module initialization in CI with the same volume layout as production.
Validate that the path parent is writable by the weaviate user before rollout.

When it happens

Trigger: Module init at server start: the path configured as PERSISTENCE_DATA_PATH (or backups path) is relative (fails immediately with 'relative backup path provided'), or os.MkdirAll of the cleaned absolute path fails due to permissions, an existing file at that path, or an unusable mount.

Common situations: BACKUP_FILESYSTEM_PATH/PERSISTENCE_DATA_PATH set to a relative value in env config; container user cannot create the directory under the given root; the path points into a not-yet-mounted or read-only volume at startup.

Related errors

AI-assisted analysis of weaviate/weaviate@75aa4b6d11 (2026-09-04). Data as JSON: /api/errors/5b934ba9db6aff8e. Report an issue: GitHub.