Fail restore for a requested path that matches nothing (closes #309)

snapshot restore said nothing about a requested path that matched no
entry in the snapshot (a typo, a relative path, or a path through a
configured snapshot path that is a symlink, whose entries are stored
under the resolved directory) and exited 0, also when nothing matched
at all. Each such path is now named in a warning, and restore returns
an error after restoring the paths that do match.

Making a path through a symlink match is not part of this change.
Judgement call: when files also fail to restore, that error is the one
returned; the unmatched paths are still named.

Model: opus-5-5

README.md

@@ -286,7 +286,9 @@ needed.
   remove orphaned blobs from remote storage. By default keeps only the latest
   snapshot per name; use `--keep-newer-than` for a rolling window.
 * `--keep-newer-than <duration>`: With `--prune`, keep snapshots newer than
-  this duration instead of only the latest (e.g. `4w`, `30d`, `6mo`, `1y`)
+  this duration instead of only the latest (e.g. `4w`, `30d`, `6mo`, `1y`).
+  Without `--prune`, or with a value that is not a valid duration, the
+  command fails before the backup starts.
 
 **`snapshot list`**: Show every snapshot known to this host — the union
 of the local index and the backup destination store — with timestamps
@@ -370,7 +372,9 @@ on the destination in one go, use `vaultik remote nuke --force`.
   store — its remote key (or an unambiguous leading part of it) as shown
   by `snapshot list`. See
   [restoring on another machine](#restoring-on-another-machine).
-* Optional path arguments to restore specific files/directories (default: all)
+* Optional path arguments to restore specific files/directories (default: all).
+  A path that matches nothing in the snapshot is named in a warning, and the
+  command exits non-zero after restoring the paths that match
 * Preserves file permissions, timestamps, ownership (ownership requires root),
   symlinks, and empty directories
 * `--verify`: After restoring, verify every file's chunk hashes match
@@ -384,12 +388,10 @@ manifest on the destination store to compute the still-referenced blob
 set and delete any blob not in that set. Step (3) reads all remote
 manifests — network cost scales with the number of snapshots. `snapshot
 create --prune` runs the same cleanup automatically; this is the
-manual entry point for the same work. If a blob cannot be deleted, the
-command (and `snapshot create --prune`) exits non-zero.
+manual entry point for the same work.
 * `--force`: Skip confirmation prompt
 * `--json`: Output stats as JSON. Also skips the confirmation prompt, as
-  `--force` does. A blob that cannot be deleted is counted in
-  `blobs_failed`, and the document is printed before the non-zero exit.
+  `--force` does.
 
 **`info`**: Display system configuration, storage settings, encryption
 recipients, and local database statistics.
@@ -403,14 +405,15 @@ orphaned blob figures are reported as unknown; `--json` gives them as
 `null`, lists the remote key of each unreadable manifest in
 `unreadable_manifests` and counts the manifests under skipped names in
 `skipped_manifest_count`. An unreadable manifest also leaves its
-snapshot's blob count and blob size unknown, `null` in `--json`.
+snapshot's blob count and blob size unknown, `null` in `--json`. A file
+under `blobs/` whose name is not a blob hash is not counted as a blob,
+since `prune` never deletes it.
 * `--json`: Output as JSON
 
 **`remote nuke`**: Delete every snapshot's metadata and every blob from the
 backup destination store, leaving the bucket prefix empty. Destructive and
 irreversible. This is the single supported way to wipe the entire
-destination store. If anything cannot be deleted, the command exits
-non-zero; running it again deletes what is left.
+destination store.
 * `--force`: Required to confirm destruction.
 
 **`database delete`**: Delete the local SQLite state database file

TODO.md

@@ -22,16 +22,13 @@ the tag exists and is exercised; what is left is merging `next` to
 
 # Completed Steps
 
-- 2026-10-13: Made `prune` and `remote nuke` exit non-zero when a delete
-  fails ([issue #290](https://git.eeqj.de/sneak/vaultik/issues/290)).
-  `prune`, and the prune step of `snapshot create --prune`, counted a
-  blob it could not delete and still exited 0; it now prints its summary
-  or `--json` document and then fails. `remote nuke` warned about a
-  snapshot's metadata it could not delete, said to run `vaultik prune`,
-  which never removes metadata, and then reported the store empty. It
-  now fails without that report and says to run `vaultik remote nuke
-  --force` again, and a successful nuke no longer advises `prune` for
-  blobs it deletes itself.
+- 2026-10-13: Stopped `remote info` counting a file under `blobs/` that
+  is not a blob as an orphaned blob
+  ([issue #295](https://git.eeqj.de/sneak/vaultik/issues/295)). A stray
+  file such as `.DS_Store` was reported as an orphaned blob and the
+  report advised running `prune`, which skips such a file and deleted
+  nothing. `remote info` now takes its blob list from the same listing
+  `prune` uses, in the table and in `--json`.
 
 - 2026-10-13: Made `snapshot remove` fail for a snapshot that does not
   exist ([issue #293](https://git.eeqj.de/sneak/vaultik/issues/293)).

internal/cli/entry_snapshot_create_prune_test.go

@@ -0,0 +1,108 @@
+package cli //nolint:testpackage // shares runEntry and the hermetic config helpers
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// Flags of `snapshot create` used to build argument vectors below.
+const (
+	flagPrune         = "--prune"
+	flagKeepNewerThan = "--keep-newer-than"
+)
+
+// TestEntrySnapshotCreateRejectsKeepNewerThanBeforeBackup checks that a
+// --keep-newer-than the post-backup prune could not use stops `snapshot
+// create` before the backup: the command fails and the destination
+// store stays empty. It used to be read only by the prune, after the
+// snapshot was uploaded, and without --prune it was ignored.
+//
+//nolint:paralleltest // replaces os.Args, os.Stdout, os.Stderr and the xdg globals
+func TestEntrySnapshotCreateRejectsKeepNewerThanBeforeBackup(t *testing.T) {
+	for _, testCase := range []struct {
+		name string
+		args []string
+	}{
+		{
+			name: "decimal in a day count",
+			args: []string{flagPrune, flagKeepNewerThan, "1.5d"},
+		},
+		{
+			name: "unknown unit",
+			args: []string{flagPrune, flagKeepNewerThan, "4x"},
+		},
+		{
+			name: "without --prune",
+			args: []string{flagKeepNewerThan, "4w"},
+		},
+	} {
+		t.Run(testCase.name, func(t *testing.T) {
+			configPath, storeDir := writeBackupConfig(t)
+
+			code, _, _ := runEntry(t, append(
+				[]string{flagConfig, configPath, cmdSnapshot, cmdCreate},
+				testCase.args...)...)
+
+			assert.Equal(t, 1, code)
+
+			stored, err := os.ReadDir(storeDir)
+			require.NoError(t, err)
+			assert.Empty(t, stored, "nothing may be uploaded")
+		})
+	}
+}
+
+// TestEntrySnapshotCreateReportsPostBackupPruneFailure makes the
+// post-backup prune fail after a good backup, by planting a manifest
+// that cannot be decoded, and checks that the failure is reported as the
+// prune's and not as a failed snapshot creation.
+//
+//nolint:paralleltest // replaces os.Args, os.Stdout, os.Stderr and the xdg globals
+func TestEntrySnapshotCreateReportsPostBackupPruneFailure(t *testing.T) {
+	configPath, storeDir := writeBackupConfig(t)
+
+	// A remote key is 64 lowercase hex characters. The prune reads every
+	// manifest on the store and fails on one it cannot decode.
+	plantedDir := filepath.Join(storeDir, "metadata", strings.Repeat("a", 64))
+	require.NoError(t, os.MkdirAll(plantedDir, 0o750))
+	require.NoError(t, os.WriteFile(
+		filepath.Join(plantedDir, "manifest.json.zst"),
+		[]byte("not a valid manifest"), 0o600))
+
+	code, _, stderr := runEntry(t,
+		flagConfig, configPath, cmdSnapshot, cmdCreate, flagPrune)
+
+	assert.Equal(t, 1, code)
+	assert.Contains(t, stderr, "Backup completed, but post-backup prune failed")
+	assert.NotContains(t, stderr, "Snapshot creation failed")
+
+	snapshots, err := os.ReadDir(filepath.Join(storeDir, "metadata"))
+	require.NoError(t, err)
+	assert.Len(t, snapshots, 2,
+		"the new snapshot is on the store beside the planted one")
+}
+
+// writeBackupConfig builds a hermetic config with one small file in its
+// source directory and an empty destination store directory. Returns the
+// config path and the store directory.
+func writeBackupConfig(t *testing.T) (string, string) {
+	t.Helper()
+
+	configPath := writeHermeticPruneConfig(t, false)
+
+	// writeHermeticPruneConfig puts the source and store directories
+	// beside the config file.
+	dir := filepath.Dir(configPath)
+	sourceDir := filepath.Join(dir, "source")
+
+	require.NoError(t, os.Mkdir(sourceDir, 0o750))
+	require.NoError(t, os.WriteFile(
+		filepath.Join(sourceDir, "file.txt"), []byte("hello"), 0o600))
+
+	return configPath, filepath.Join(dir, "store")
+}

internal/cli/snapshot.go

@@ -71,6 +71,11 @@ otherwise from the platform config directory (~/.config/vaultik/config.yml
 on Linux), then /etc/vaultik/config.yml.`,
 		Args: cobra.ArbitraryArgs,
 		RunE: func(cmd *cobra.Command, args []string) error {
+			err := opts.Validate()
+			if err != nil {
+				return err
+			}
+
 			// Pass snapshot names from args
 			opts.Snapshots = args
 			// --skip-errors is a global flag on the root command.
@@ -97,6 +102,13 @@ on Linux), then /etc/vaultik/config.yml.`,
 			}, func(v *vaultik.Vaultik) error {
 				return v.CreateSnapshot(opts)
 			}, func(err error) {
+				if errors.Is(err, vaultik.ErrPostBackupPruneFailed) {
+					log.Error("Post-backup prune failed", "error", err)
+					ReportErrorf("Backup completed, but %v", err)
+
+					return
+				}
+
 				log.Error("Snapshot creation failed", "error", err)
 				ReportErrorf("Snapshot creation failed: %v", err)
 			})

internal/cli/snapshot_restore.go

@@ -30,6 +30,8 @@ This command will restore files from the specified snapshot to the
 target directory.
 If no paths are specified, all files are restored.
 If paths are specified, only matching files/directories are restored.
+A path that matches nothing in the snapshot is named in a warning, and
+the command exits non-zero after restoring the paths that match.
 
 The snapshot may be named by its ID or, when restoring on a host with no
 local index, by the remote key that 'snapshot list' prints for a

internal/storage/faultstore/faultstore.go

@@ -1,16 +1,15 @@
 // Package faultstore provides a storage.Storer wrapper that injects
 // faults on demand, so tests can reproduce the failure modes a real
 // backend exhibits: an upload that fails partway, a backend that reports
-// success while storing nothing, reads that return corrupt or truncated
-// bytes, and a delete the backend refuses. It is the seam called for by
-// the fault-injection tests (sneak/vaultik issue 72) and is meant to be
-// reused by future tests rather than re-implemented per case.
+// success while storing nothing, and reads that return corrupt or
+// truncated bytes. It is the seam called for by the fault-injection
+// tests (sneak/vaultik issue 72) and is meant to be reused by future
+// tests rather than re-implemented per case.
 //
-// The wrapper delegates every method to the inner Storer. Three hooks
-// change that: OnPut decides the fate of each write, OnGet decides how
-// each read's bytes are returned, and OnDelete decides whether each
-// delete fails. All are keyed by the object key, so a test can fault
-// only blobs, only metadata, or a single object.
+// The wrapper delegates every method to the inner Storer. Two hooks
+// change that: OnPut decides the fate of each write, and OnGet decides
+// how each read's bytes are returned. Both are keyed by the object key,
+// so a test can fault only blobs, only metadata, or a single object.
 package faultstore
 
 import (
@@ -26,10 +25,6 @@ import (
 // ErrInjectedUpload is returned by a Put the OnPut hook chose to fail.
 var ErrInjectedUpload = errors.New("faultstore: injected upload failure")
 
-// ErrInjectedDelete is returned by a Delete the OnDelete hook chose to
-// fail.
-var ErrInjectedDelete = errors.New("faultstore: injected delete failure")
-
 // PutAction is the disposition OnPut assigns to a write.
 type PutAction int
 
@@ -71,11 +66,6 @@ type Storer struct {
 	// OnGet, when set, is consulted for every Get with the object key
 	// and damages the returned bytes accordingly.
 	OnGet func(key string) GetFault
-
-	// OnDelete, when set, is consulted before every Delete with the
-	// object key. Returning true fails the delete and leaves the object
-	// in place.
-	OnDelete func(key string) bool
 }
 
 // New wraps inner. inner must be non-nil.
@@ -164,12 +154,8 @@ func (f *Storer) Stat(ctx context.Context, key string) (*storage.ObjectInfo, err
 	return f.inner.Stat(ctx, key)
 }
 
-// Delete removes the object unless OnDelete fails the delete.
+// Delete delegates unchanged.
 func (f *Storer) Delete(ctx context.Context, key string) error {
-	if f.OnDelete != nil && f.OnDelete(key) {
-		return fmt.Errorf("%w for %q", ErrInjectedDelete, key)
-	}
-
 	return f.inner.Delete(ctx, key)
 }
 

internal/vaultik/info.go

@@ -167,10 +167,6 @@ const (
 	// metadataKeyParts is the minimum "/"-separated segment count of a
 	// metadata object key (metadata/<snapshot-id>/<filename>).
 	metadataKeyParts = 3
-
-	// blobKeyParts is the minimum "/"-separated segment count of a blob
-	// object key (blobs/<aa>/<bb>/<hash>).
-	blobKeyParts = 4
 )
 
 // SnapshotMetadataInfo contains information about a single snapshot's metadata
@@ -454,23 +450,16 @@ func (v *Vaultik) scanRemoteBlobStorage(
 		v.stdoutf("Scanning blobs...\n")
 	}
 
-	blobCh := v.Storage.ListStream(v.ctx, "blobs/")
-	allBlobs := make(map[string]int64)
+	// Use prune's listing, so a file under blobs/ that prune would never
+	// delete is not counted as a blob, and so not as an orphaned one.
+	allBlobs, err := v.listAllRemoteBlobs()
+	if err != nil {
+		return err
+	}
 
-	for obj := range blobCh {
-		if obj.Err != nil {
-			return fmt.Errorf("listing blobs: %w", obj.Err)
-		}
-
-		parts := strings.Split(obj.Key, "/")
-		if len(parts) < blobKeyParts {
-			continue
-		}
-
-		hash := parts[3]
-		allBlobs[hash] = obj.Size
+	for _, size := range allBlobs {
 		result.TotalBlobCount++
-		result.TotalBlobSize += obj.Size
+		result.TotalBlobSize += size
 	}
 
 	// A blob named only by a manifest that could not be read, or by one

internal/vaultik/nuke_remote_test.go

@@ -5,14 +5,12 @@ import (
 	"io/fs"
 	"os"
 	"path/filepath"
-	"strings"
 	"testing"
 
 	"github.com/stretchr/testify/assert"
 	"github.com/stretchr/testify/require"
 	"sneak.berlin/go/vaultik/internal/log"
 	"sneak.berlin/go/vaultik/internal/snapshot"
-	"sneak.berlin/go/vaultik/internal/storage/faultstore"
 )
 
 // TestNukeRemoteLeavesNoFiles checks that remote nuke leaves no file
@@ -25,7 +23,7 @@ func TestNukeRemoteLeavesNoFiles(t *testing.T) {
 
 	ctx := context.Background()
 	storeDir := filepath.Join(t.TempDir(), "store")
-	v, repos, out := backUpToFileDestination(ctx, t, storeDir)
+	v, repos, _ := backUpToFileDestination(ctx, t, storeDir)
 
 	snapshots, err := repos.Snapshots.ListRecent(ctx, listRecentTestLimit)
 	require.NoError(t, err)
@@ -63,82 +61,4 @@ func TestNukeRemoteLeavesNoFiles(t *testing.T) {
 		})
 	require.NoError(t, err)
 	assert.Empty(t, files)
-
-	// Nuke deletes the blobs itself, so advice to run prune is wrong.
-	assert.Contains(t, out.String(), "Backup destination store is now empty.")
-	assert.NotContains(t, out.String(), "vaultik prune")
-}
-
-// TestNukeRemoteFailsWhenADeleteFails checks that remote nuke returns an
-// error when a snapshot's metadata or a blob cannot be deleted, does not
-// report the store empty, and advises running nuke again: prune deletes
-// no metadata.
-func TestNukeRemoteFailsWhenADeleteFails(t *testing.T) {
-	log.Initialize(log.Config{})
-	t.Parallel()
-
-	for _, refusedPrefix := range []string{"metadata/", "blobs/"} {
-		t.Run(refusedPrefix, func(t *testing.T) {
-			t.Parallel()
-
-			ctx := context.Background()
-			storeDir := filepath.Join(t.TempDir(), "store")
-			v, _, out := backUpToFileDestination(ctx, t, storeDir)
-
-			store := faultstore.New(v.Storage)
-			store.OnDelete = func(key string) bool {
-				return strings.HasPrefix(key, refusedPrefix)
-			}
-			v.Storage = store
-
-			require.Error(t, v.NukeRemote(true))
-
-			assert.NotContains(t, out.String(), "now empty")
-			assert.Contains(t, out.String(), "vaultik remote nuke --force")
-			assert.NotContains(t, out.String(), "vaultik prune")
-		})
-	}
-}
-
-// TestNukeRemoteRefusesAnotherDestinationWithoutRetryAdvice checks that
-// remote nuke, when the local index belongs to a different destination
-// than the configured one, fails without advising to run nuke again:
-// that run would fail the same way.
-func TestNukeRemoteRefusesAnotherDestinationWithoutRetryAdvice(t *testing.T) {
-	log.Initialize(log.Config{})
-	t.Parallel()
-
-	ctx := context.Background()
-	storeDir := filepath.Join(t.TempDir(), "store")
-	v, _, out := backUpToFileDestination(ctx, t, storeDir)
-
-	v.Config.StorageURL = "file://" + filepath.Join(t.TempDir(), "elsewhere")
-
-	err := v.NukeRemote(true)
-
-	require.ErrorContains(t, err, "bound to a different backup destination")
-	assert.NotContains(t, out.String(), "vaultik remote nuke --force")
-}
-
-// TestNukeRemoteFailsWhenALocalSnapshotCannotBeRemoved checks that a
-// snapshot remote nuke cannot remove from the local index fails the
-// run: nuke then leaves that snapshot's metadata on the destination
-// store.
-func TestNukeRemoteFailsWhenALocalSnapshotCannotBeRemoved(t *testing.T) {
-	log.Initialize(log.Config{})
-	t.Parallel()
-
-	ctx := context.Background()
-	storeDir := filepath.Join(t.TempDir(), "store")
-	v, _, out := backUpToFileDestination(ctx, t, storeDir)
-
-	_, err := v.DB.Conn().ExecContext(ctx, `
-		CREATE TRIGGER refuse_snapshot_delete BEFORE DELETE ON snapshots
-		BEGIN SELECT RAISE(ABORT, 'simulated index error'); END`)
-	require.NoError(t, err)
-
-	require.Error(t, v.NukeRemote(true))
-
-	assert.NotContains(t, out.String(), "now empty")
-	assert.Contains(t, out.String(), "vaultik remote nuke --force")
 }

internal/vaultik/prune.go

@@ -19,18 +19,14 @@ type PruneOptions struct {
 var errNukeRequiresForce = errors.New(
 	"nuke requires --force (this deletes ALL remote snapshots and blobs)")
 
-// errBlobDeleteFailed reports unreferenced blobs prune could not delete.
-var errBlobDeleteFailed = errors.New("blob(s) could not be deleted")
-
-// nukeCommandHint is the command suggested when a remote nuke could not
-// delete everything: running it again deletes what is left, which
-// `vaultik prune` does not do for snapshot metadata.
-const nukeCommandHint = "vaultik remote nuke --force"
-
 // metadataDirName is the top-level remote directory holding snapshot
 // metadata.
 const metadataDirName = "metadata"
 
+// blobKeyParts is the "/"-separated segment count of a blob object key
+// (blobs/<aa>/<bb>/<hash>).
+const blobKeyParts = 4
+
 // NukeRemote deletes every snapshot's metadata and every blob from remote
 // storage, along with any object an upload cut off part-way left under a
 // temporary `.partial` name. After this returns successfully the bucket
@@ -43,29 +39,6 @@ func (v *Vaultik) NukeRemote(force bool) error {
 		return errNukeRequiresForce
 	}
 
-	// Checked before anything is deleted: running nuke again would fail
-	// the same way, so the advice below must not follow this error.
-	err := v.EnsureStorageBinding()
-	if err != nil {
-		return err
-	}
-
-	err = v.emptyDestinationStore()
-	if err != nil {
-		v.UI.Warningf("Run '%s' again to delete what is left on the "+
-			"backup destination store.", nukeCommandHint)
-
-		return err
-	}
-
-	v.UI.Completef("Backup destination store is now empty.")
-
-	return nil
-}
-
-// emptyDestinationStore does the deleting for NukeRemote and stops at
-// the first step that fails.
-func (v *Vaultik) emptyDestinationStore() error {
 	v.UI.Beginf("Removing all snapshot metadata from backup destination store.")
 
 	_, err := v.RemoveAllSnapshots(&RemoveOptions{Force: true})
@@ -89,6 +62,8 @@ func (v *Vaultik) emptyDestinationStore() error {
 		}
 	}
 
+	v.UI.Completef("Backup destination store is now empty.")
+
 	return nil
 }
 
@@ -191,17 +166,14 @@ func (v *Vaultik) PruneBlobs(opts *PruneOptions) error {
 	v.deleteUnreferencedBlobs(unreferencedBlobs, allBlobs, result)
 
 	if opts.JSON {
-		err = v.outputPruneBlobsJSON(result)
-		if err != nil {
-			return err
-		}
-	} else {
-		v.stdoutf("\nDeleted %d blob(s) totaling %s\n",
-			result.BlobsDeleted, ubytes(result.BytesFreed))
+		return v.outputPruneBlobsJSON(result)
 	}
 
+	v.stdoutf("\nDeleted %d blob(s) totaling %s\n",
+		result.BlobsDeleted, ubytes(result.BytesFreed))
+
 	if result.BlobsFailed > 0 {
-		return fmt.Errorf("%d %w", result.BlobsFailed, errBlobDeleteFailed)
+		v.stdoutf("Failed to delete %d blob(s)\n", result.BlobsFailed)
 	}
 
 	return nil

internal/vaultik/prune_delete_failure_test.go

@@ -1,98 +0,0 @@
-package vaultik_test
-
-import (
-	"context"
-	"encoding/json"
-	"os"
-	"path/filepath"
-	"strings"
-	"testing"
-
-	"github.com/stretchr/testify/assert"
-	"github.com/stretchr/testify/require"
-	"sneak.berlin/go/vaultik/internal/log"
-	"sneak.berlin/go/vaultik/internal/storage/faultstore"
-	"sneak.berlin/go/vaultik/internal/vaultik"
-)
-
-// refuseBlobDeletes is an OnDelete hook that fails every blob delete.
-func refuseBlobDeletes(key string) bool {
-	return strings.HasPrefix(key, "blobs/")
-}
-
-// TestPruneBlobs_FailedDeleteReturnsError checks that prune returns an
-// error, so the command exits non-zero, when an unreferenced blob cannot
-// be deleted.
-func TestPruneBlobs_FailedDeleteReturnsError(t *testing.T) {
-	log.Initialize(log.Config{})
-	t.Parallel()
-
-	env := newListEnv(t)
-
-	// The store holds no manifest, so nothing references this blob.
-	addBlob(t, env.store.testStorer, testBlobHashA)
-
-	store := faultstore.New(env.store)
-	store.OnDelete = refuseBlobDeletes
-	env.v.Storage = store
-
-	err := env.v.PruneBlobs(&vaultik.PruneOptions{Force: true})
-
-	require.ErrorContains(t, err, "1 blob(s) could not be deleted")
-}
-
-// TestPruneBlobs_JSONFailedDeleteReturnsError checks that prune --json
-// prints its document and then returns an error when an unreferenced
-// blob cannot be deleted.
-func TestPruneBlobs_JSONFailedDeleteReturnsError(t *testing.T) {
-	log.Initialize(log.Config{})
-	t.Parallel()
-
-	env := newListEnv(t)
-	addBlob(t, env.store.testStorer, testBlobHashA)
-
-	store := faultstore.New(env.store)
-	store.OnDelete = refuseBlobDeletes
-	env.v.Storage = store
-
-	err := env.v.PruneBlobs(&vaultik.PruneOptions{JSON: true})
-
-	require.Error(t, err, "prune must fail when a blob cannot be deleted")
-
-	var result vaultik.PruneBlobsResult
-
-	require.NoError(t, json.Unmarshal(env.stdout.Bytes(), &result),
-		"stdout must hold the JSON document, got:\n%s", env.stdout.String())
-	assert.Equal(t, 1, result.BlobsFailed)
-	assert.Equal(t, 0, result.BlobsDeleted)
-}
-
-// TestCreateSnapshotPrune_FailedBlobDeleteReturnsError checks that the
-// prune step of snapshot create --prune fails the run when an
-// unreferenced blob cannot be deleted.
-func TestCreateSnapshotPrune_FailedBlobDeleteReturnsError(t *testing.T) {
-	log.Initialize(log.Config{})
-	t.Parallel()
-
-	ctx := context.Background()
-	storeDir := filepath.Join(t.TempDir(), "store")
-	v, _, _ := backUpToFileDestination(ctx, t, storeDir)
-
-	// No snapshot references this blob, so the prune step deletes it.
-	orphan := filepath.Join(storeDir, "blobs", testBlobHashA[:2],
-		testBlobHashA[2:4], testBlobHashA)
-	require.NoError(t, os.MkdirAll(filepath.Dir(orphan), 0o750))
-	require.NoError(t, os.WriteFile(orphan, []byte("orphan"), 0o600))
-
-	store := faultstore.New(v.Storage)
-	store.OnDelete = refuseBlobDeletes
-	v.Storage = store
-
-	err := v.CreateSnapshot(&vaultik.SnapshotCreateOptions{
-		Cron:  true,
-		Prune: true,
-	})
-
-	require.ErrorContains(t, err, "1 blob(s) could not be deleted")
-	assert.FileExists(t, orphan)
-}

internal/vaultik/remote_info_test.go

@@ -185,6 +185,39 @@ func TestRemoteInfo_SkipsNonConformingMetadataName(t *testing.T) {
 	assert.NotContains(t, doc, "unreadable_manifests")
 }
 
+// TestRemoteInfo_DoesNotCountNonBlobFileUnderBlobs checks that a file
+// under blobs/ whose name is not a blob hash is not counted as a blob.
+// prune never deletes such a file, so counting it as an orphaned blob
+// would advise a prune that removes nothing.
+func TestRemoteInfo_DoesNotCountNonBlobFileUnderBlobs(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	env := newListEnv(t)
+	env.addRemote(t, listRemoteID, time.Date(2026, 3, 2, 0, 0, 0, 0, time.UTC))
+	addBlob(t, env.store.testStorer, testBlobHashA)
+	require.NoError(t, env.store.Put(context.Background(),
+		"blobs/"+testBlobHashA[:2]+"/"+testBlobHashA[2:4]+"/.DS_Store",
+		bytes.NewReader([]byte("junk"))))
+
+	require.NoError(t, env.v.RemoteInfo(false))
+
+	text := env.stdout.String()
+	assert.Contains(t, text, "Total blobs on remote:      1 (")
+	assert.Contains(t, text, "Orphaned (unreferenced):    0 (")
+	assert.NotContains(t, text, "vaultik prune")
+
+	env.stdout.Reset()
+	require.NoError(t, env.v.RemoteInfo(true))
+
+	var doc map[string]any
+
+	require.NoError(t, json.Unmarshal(env.stdout.Bytes(), &doc))
+	assert.InDelta(t, 1, doc["total_blob_count"], 0)
+	assert.InDelta(t, 0, doc["orphaned_blob_count"], 0)
+	assert.InDelta(t, 0, doc["orphaned_blob_size"], 0)
+}
+
 // TestRemoteInfo_DirectoryWithoutManifestLeavesOrphansKnown checks that
 // a directory under metadata/ holding no manifest.json.zst, such as one
 // left by a backup interrupted before its manifest upload, leaves the

internal/vaultik/remove_snapshot_test.go

@@ -476,8 +476,7 @@ func TestRemoveAllSnapshots_WithForce(t *testing.T) {
 	out := tv.Stdout.String()
 	assert.Contains(t, out, "Removed 2 snapshot(s)")
 	assert.Contains(t, out, "Removed snapshot metadata from remote storage")
-	// Remote nuke, the only caller, deletes the blobs next itself.
-	assert.NotContains(t, out, "vaultik prune")
+	assert.Contains(t, out, "vaultik prune")
 }
 
 func TestRemoveAllSnapshots_DryRun(t *testing.T) {

internal/vaultik/restore.go

@@ -27,6 +27,7 @@ import (
 // Sentinel errors for restore failures.
 var (
 	errFilesFailedRestore    = errors.New("file(s) failed to restore")
+	errPathsNotInSnapshot    = errors.New("requested path(s) not in the snapshot")
 	errFilesFailedVerify     = errors.New("files failed verification")
 	errDecryptionKeyRequired = errors.New(
 		"decryption key required for restore\n\n" +
@@ -149,7 +150,7 @@ func (v *Vaultik) Restore(opts *RestoreOptions) error {
 	repos := database.NewRepositories(tempDB)
 
 	// Step 2: Get list of files to restore
-	files, err := v.getFilesToRestore(v.ctx, repos, opts.Paths)
+	files, unmatched, err := v.getFilesToRestore(v.ctx, repos, opts.Paths)
 	if err != nil {
 		return fmt.Errorf("getting files to restore: %w", err)
 	}
@@ -158,7 +159,7 @@ func (v *Vaultik) Restore(opts *RestoreOptions) error {
 		log.Warn("No files found to restore")
 		v.UI.Warningf("No files found to restore.")
 
-		return nil
+		return v.reportUnmatchedPaths(unmatched)
 	}
 
 	log.Info("Found files to restore", "count", len(files))
@@ -198,14 +199,16 @@ func (v *Vaultik) Restore(opts *RestoreOptions) error {
 		v.UI.Duration(result.Duration),
 	)
 
-	return v.finishRestore(repos, files, opts, result)
+	return v.finishRestore(repos, files, unmatched, opts, result)
 }
 
 // finishRestore emits the post-restore warnings, runs optional
-// verification, and converts any failed-file count into an error.
+// verification, and converts any failed-file count or requested path
+// that matched nothing into an error.
 func (v *Vaultik) finishRestore(
 	repos *database.Repositories,
 	files []*database.File,
+	unmatched []string,
 	opts *RestoreOptions,
 	result *RestoreResult,
 ) error {
@@ -223,6 +226,8 @@ func (v *Vaultik) finishRestore(
 		}
 	}
 
+	unmatchedErr := v.reportUnmatchedPaths(unmatched)
+
 	// Run verification if requested
 	if opts.Verify {
 		err := v.handleRestoreVerification(repos, files, opts, result)
@@ -235,7 +240,23 @@ func (v *Vaultik) finishRestore(
 		return fmt.Errorf("%d %w", result.FilesFailed, errFilesFailedRestore)
 	}
 
-	return nil
+	return unmatchedErr
+}
+
+// reportUnmatchedPaths warns, by name, about each requested path that
+// matched nothing in the snapshot, and returns an error counting them,
+// or nil when there are none.
+func (v *Vaultik) reportUnmatchedPaths(unmatched []string) error {
+	if len(unmatched) == 0 {
+		return nil
+	}
+
+	for _, path := range unmatched {
+		log.Warn("Requested path matches nothing in the snapshot", "path", path)
+		v.UI.Warningf("%s matches nothing in the snapshot.", v.UI.Path(path))
+	}
+
+	return fmt.Errorf("%d %w", len(unmatched), errPathsNotInSnapshot)
 }
 
 // restoreIdentities parses the configured age secret key once into every
@@ -812,27 +833,34 @@ func (v *Vaultik) materializeSnapshotDB(
 	return db, tempDir, nil
 }
 
-// getFilesToRestore returns the list of files to restore based on path filters
+// getFilesToRestore returns the list of files to restore based on path
+// filters, and the filters, as given, that matched no file.
 func (v *Vaultik) getFilesToRestore(
 	ctx context.Context, repos *database.Repositories, pathFilters []string,
-) ([]*database.File, error) {
+) ([]*database.File, []string, error) {
 	// If no filters, get all files
 	if len(pathFilters) == 0 {
-		return repos.Files.ListAll(ctx)
+		files, err := repos.Files.ListAll(ctx)
+
+		return files, nil, err
 	}
 
 	// Get files matching the path filters
-	var result []*database.File
+	var (
+		result    []*database.File
+		unmatched []string
+	)
 
 	seen := make(map[string]bool)
 
 	for _, filter := range pathFilters {
-		// Normalize the filter path
-		filter = filepath.Clean(filter)
-
-		files, err := repos.Files.ListUnderPath(ctx, filter)
+		files, err := repos.Files.ListUnderPath(ctx, filepath.Clean(filter))
 		if err != nil {
-			return nil, fmt.Errorf("listing files under %s: %w", filter, err)
+			return nil, nil, fmt.Errorf("listing files under %s: %w", filter, err)
+		}
+
+		if len(files) == 0 {
+			unmatched = append(unmatched, filter)
 		}
 
 		for _, file := range files {
@@ -843,7 +871,7 @@ func (v *Vaultik) getFilesToRestore(
 		}
 	}
 
-	return result, nil
+	return result, unmatched, nil
 }
 
 // buildChunkToBlobMap creates a mapping from chunk hash to blob information

internal/vaultik/restore_unmatched_path_test.go

@@ -0,0 +1,142 @@
+package vaultik_test
+
+import (
+	"bytes"
+	"context"
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"github.com/spf13/afero"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"sneak.berlin/go/vaultik/internal/config"
+	"sneak.berlin/go/vaultik/internal/database"
+	"sneak.berlin/go/vaultik/internal/log"
+	"sneak.berlin/go/vaultik/internal/storage"
+	"sneak.berlin/go/vaultik/internal/ui"
+	"sneak.berlin/go/vaultik/internal/vaultik"
+)
+
+// These tests cover https://git.eeqj.de/sneak/vaultik/issues/309: a path
+// given to restore that matches nothing in the snapshot is named in a
+// warning and makes the restore fail, after the paths that do match are
+// restored.
+
+func TestRestoreNamesUnmatchedPathAndRestoresTheMatchingOne(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	fs := afero.NewOsFs()
+	tempDir := t.TempDir()
+	dataDir := filepath.Join(tempDir, "src")
+	storeDir := filepath.Join(tempDir, "remote")
+	restoreDir := filepath.Join(tempDir, "restored")
+	dbPath := filepath.Join(tempDir, "index.sqlite")
+
+	ctx := context.Background()
+	cfg := faultTestConfig()
+	files := writeFaultSourceTree(t, fs, dataDir)
+
+	store, err := storage.NewFileStorer(storeDir)
+	require.NoError(t, err)
+
+	db, err := database.New(ctx, dbPath)
+	require.NoError(t, err)
+
+	id := fullFaultBackup(ctx, t, fs, store, cfg,
+		database.NewRepositories(db), dataDir, dbPath, "unmatched")
+	require.NoError(t, db.Close())
+
+	matched := filepath.Join(dataDir, "small.txt")
+	unmatched := filepath.Join(dataDir, "typo.txt")
+
+	var out bytes.Buffer
+
+	v := newReaderVaultik(ctx, cfg, store, nil, fs)
+	v.UI = ui.NewWithColor(&out, false)
+
+	err = v.Restore(&vaultik.RestoreOptions{
+		SnapshotID: id,
+		TargetDir:  restoreDir,
+		Paths:      []string{matched, unmatched},
+	})
+
+	require.Error(t, err, "a path that matches nothing must fail the restore")
+	assert.Contains(t, out.String(), unmatched,
+		"the path that matches nothing must be named")
+	assert.NotContains(t, out.String(), matched,
+		"the path that matches must not be reported")
+
+	got, err := afero.ReadFile(fs, filepath.Join(restoreDir, matched))
+	require.NoError(t, err, "the path that matches must still be restored")
+	assert.Equal(t, files[matched], got)
+}
+
+// When no requested path matches, nothing is restored and each path is
+// named. One path is relative. The other goes through the symlink that
+// is the snapshot's configured path, while the entries are stored under
+// the directory the symlink points to.
+func TestRestoreNamesEveryPathWhenNothingMatches(t *testing.T) {
+	log.Initialize(log.Config{})
+	t.Parallel()
+
+	const snapshotName = "linked"
+
+	fs := afero.NewOsFs()
+	tempDir := t.TempDir()
+	dataDir := filepath.Join(tempDir, "src")
+	linkDir := filepath.Join(tempDir, "srclink")
+	storeDir := filepath.Join(tempDir, "remote")
+	restoreDir := filepath.Join(tempDir, "restored")
+	dbPath := filepath.Join(tempDir, "index.sqlite")
+
+	ctx := context.Background()
+	writeFaultSourceTree(t, fs, dataDir)
+	require.NoError(t, os.Symlink(dataDir, linkDir))
+
+	cfg := faultTestConfig()
+	cfg.IndexPath = dbPath
+	cfg.ChunkSize = config.Size(faultChunkSize)
+	cfg.Snapshots = map[string]config.SnapshotConfig{
+		snapshotName: {Paths: []string{linkDir}},
+	}
+
+	store, err := storage.NewFileStorer(storeDir)
+	require.NoError(t, err)
+
+	db, err := database.New(ctx, dbPath)
+	require.NoError(t, err)
+
+	repos := database.NewRepositories(db)
+	v := newBackupVaultik(ctx, cfg, store, repos, db, fs)
+
+	require.NoError(t, backUp(v, snapshotName))
+
+	id := localSnapshotID(ctx, t, repos, snapshotName)
+	require.NoError(t, db.Close())
+
+	throughLink := filepath.Join(linkDir, "sub")
+	relative := strings.TrimPrefix(filepath.Join(dataDir, "small.txt"), "/")
+
+	var out bytes.Buffer
+
+	reader := newReaderVaultik(ctx, cfg, store, nil, fs)
+	reader.UI = ui.NewWithColor(&out, false)
+
+	err = reader.Restore(&vaultik.RestoreOptions{
+		SnapshotID: id,
+		TargetDir:  restoreDir,
+		Paths:      []string{throughLink, relative},
+	})
+
+	require.Error(t, err, "a restore that matches nothing must fail")
+	assert.Contains(t, out.String(), throughLink,
+		"the path through the symlink must be named")
+	assert.Contains(t, out.String(), relative,
+		"the relative path must be named")
+
+	_, err = fs.Stat(restoreDir)
+	assert.True(t, os.IsNotExist(err), "nothing must be restored")
+}

internal/vaultik/snapshot.go

@@ -24,13 +24,18 @@ var (
 	errSnapshotVerifyFailed = errors.New("verification failed")
 	errRemoveAllNeedsForce  = errors.New("--all requires --force")
 	errSnapshotNotFound     = errors.New("snapshot not found")
-	errSnapshotRemoveFailed = errors.New("snapshot(s) could not be removed")
 	errInvalidTableName     = errors.New("invalid table name")
 	errNoAgeRecipients      = errors.New(
 		"creating a snapshot needs at least one public key in " +
 			"age_recipients (generate a keypair with: age-keygen)")
+	errKeepNewerThanNeedsPrune = errors.New("--keep-newer-than requires --prune")
 )
 
+// ErrPostBackupPruneFailed wraps a failure of the post-backup prune,
+// which runs only after every snapshot was created and uploaded, so the
+// caller can report it apart from a failed backup.
+var ErrPostBackupPruneFailed = errors.New("post-backup prune failed")
+
 // listRecentLimit caps how many snapshot rows are fetched from the
 // local index for listing and purge operations.
 const listRecentLimit = 10000
@@ -46,6 +51,26 @@ type SnapshotCreateOptions struct {
 	Snapshots     []string // Optional list of snapshot names to process (empty = all)
 }
 
+// Validate fails when KeepNewerThan is set without Prune or is not a
+// valid duration. Only the post-backup prune reads KeepNewerThan, after
+// the backup, so the caller checks it before starting one.
+func (opts *SnapshotCreateOptions) Validate() error {
+	if opts.KeepNewerThan == "" {
+		return nil
+	}
+
+	if !opts.Prune {
+		return errKeepNewerThanNeedsPrune
+	}
+
+	_, err := parseDuration(opts.KeepNewerThan)
+	if err != nil {
+		return fmt.Errorf("--keep-newer-than: %w", err)
+	}
+
+	return nil
+}
+
 // CreateSnapshot executes the snapshot creation operation
 func (v *Vaultik) CreateSnapshot(opts *SnapshotCreateOptions) error {
 	// config.Load accepts an empty list, since listing, verifying and
@@ -124,7 +149,7 @@ func (v *Vaultik) CreateSnapshot(opts *SnapshotCreateOptions) error {
 	if opts.Prune {
 		err = v.runPostBackupPrune(snapshotNames, opts.KeepNewerThan)
 		if err != nil {
-			return fmt.Errorf("post-backup prune: %w", err)
+			return fmt.Errorf("%w: %w", ErrPostBackupPruneFailed, err)
 		}
 	}
 
@@ -1514,8 +1539,8 @@ func (v *Vaultik) handleRemoveAllDryRun(
 
 // executeRemoveAll deletes every local snapshot and, unless LocalOnly
 // is set, every corresponding remote metadata directory plus any
-// orphan remote keys. Blobs are not touched. It returns an error when
-// any snapshot could not be removed.
+// orphan remote keys. Blobs are not touched; the printed prune-command
+// hint is the next step.
 func (v *Vaultik) executeRemoveAll(
 	localSnaps, orphanRemoteKeys []string, opts *RemoveOptions,
 ) (*RemoveResult, error) {
@@ -1529,11 +1554,18 @@ func (v *Vaultik) executeRemoveAll(
 
 	result := &RemoveResult{}
 
-	failures := v.removeAllLocalSnapshots(localSnaps, opts, result)
+	remoteErrors := v.removeAllLocalSnapshots(localSnaps, opts, result)
 
 	if !opts.LocalOnly {
-		failures += v.removeAllOrphanRemotes(orphanRemoteKeys, result)
-		result.RemoteRemoved = failures == 0
+		remoteErrors += v.removeAllOrphanRemotes(orphanRemoteKeys, result)
+
+		if remoteErrors == 0 {
+			result.RemoteRemoved = true
+		} else if v.UI != nil {
+			v.UI.Warningf("Some remote metadata deletions failed. Run '%s' "+
+				"once the remote is healthy to clean up unreferenced blobs.",
+				pruneCommandHint)
+		}
 	}
 
 	if v.SnapshotManager != nil {
@@ -1543,10 +1575,6 @@ func (v *Vaultik) executeRemoveAll(
 		}
 	}
 
-	if failures > 0 {
-		return result, fmt.Errorf("%d %w", failures, errSnapshotRemoveFailed)
-	}
-
 	if opts.JSON {
 		return result, v.outputRemoveJSON(result)
 	}
@@ -1555,6 +1583,9 @@ func (v *Vaultik) executeRemoveAll(
 
 	if !opts.LocalOnly && result.RemoteRemoved {
 		v.printlnStdout("Removed snapshot metadata from remote storage")
+		v.stdoutf("\nNote: Removed snapshots' blobs remain on the remote. "+
+			"Run '%s' to delete any blobs no longer referenced by any "+
+			"remaining remote snapshot.\n", pruneCommandHint)
 	}
 
 	return result, nil
@@ -1597,13 +1628,12 @@ func (v *Vaultik) deleteIncompleteSnapshot(snapshotIDStr string, id any) bool {
 }
 
 // removeAllLocalSnapshots removes each known local snapshot (and, unless
-// --local-only, its remote metadata), returning the number of snapshots
-// it could not remove. A snapshot left in the local index keeps its
-// remote metadata too, since it is not an orphan remote key.
+// --local-only, its remote metadata), returning the number of remote
+// deletion failures.
 func (v *Vaultik) removeAllLocalSnapshots(
 	localSnaps []string, opts *RemoveOptions, result *RemoveResult,
 ) int {
-	failures := 0
+	remoteErrors := 0
 
 	for _, snapshotID := range localSnaps {
 		log.Info("Removing snapshot", "snapshot_id", snapshotID)
@@ -1613,8 +1643,6 @@ func (v *Vaultik) removeAllLocalSnapshots(
 			log.Error("Failed to remove from local database",
 				"snapshot_id", snapshotID, "error", err)
 
-			failures++
-
 			continue
 		}
 
@@ -1625,14 +1653,14 @@ func (v *Vaultik) removeAllLocalSnapshots(
 				log.Warn("Failed to remove snapshot metadata from remote",
 					"snapshot_id", snapshotID, "error", err)
 
-				failures++
+				remoteErrors++
 			}
 		}
 
 		result.SnapshotsRemoved = append(result.SnapshotsRemoved, snapshotID)
 	}
 
-	return failures
+	return remoteErrors
 }
 
 // removeAllOrphanRemotes deletes remote snapshot metadata that has no