benbjohnson/litestream · error

oss: failed to delete files:

Error message

oss: failed to delete files:

What it means

The Azure Blob (oss) replica client aggregates per-key failures from a batched delete into a single error listing every key that could not be deleted, prefixed with 'oss: failed to delete files:'. DeleteLTXFiles, DeleteAll and internal callers raise it when the multi-delete API reports errors for individual objects.

Source

Thrown at oss/replica_client.go:725

		if obj.Key == nil {
			continue
		}
		if _, ok := deleted[*obj.Key]; !ok {
			failed = append(failed, *obj.Key)
		}
	}

	if len(failed) == 0 {
		return nil
	}

	// Build error message listing failed keys
	var b strings.Builder
	b.WriteString("oss: failed to delete files:")
	for _, key := range failed {
		fmt.Fprintf(&b, "\n%s", key)
	}
	return errors.New(b.String())
}

View on GitHub (pinned to 4ed7a308f6)

Solutions

1. Read the individual keys listed under the error header to identify which blobs failed and why
2. Verify the configured credentials (SAS token or shared key) grant delete (and list) permission on the container
3. Check whether an Azure storage lifecycle rule deleted the blobs already and adjust retention so litestream does not double-delete
4. Retry the delete; transient throttling is a common cause of partial batch failures

Example fix

// before
if err := replica.DeleteAll(ctx); err != nil {
    return err
}
// after
if err := replica.DeleteAll(ctx); err != nil {
    if strings.Contains(err.Error(), "oss: failed to delete files:") {
        log.Printf("partial delete failure; check listed keys and container permissions: %v", err)
    }
    return err
}

// pre-check delete permission with a harmless probe
_, err := client.TestPermission(ctx, container, ".litestream-delete-probe")

func isOSSBatchDeleteErr(err error) bool {
    return strings.Contains(err.Error(), "oss: failed to delete files:")
}

if err := replicaClient.DeleteAll(ctx); err != nil {
    if isOSSBatchDeleteErr(err) {
        // parse listed keys, verify container permissions, retry transient ones
        log.Printf("partial batch delete: %v", err)
    }
    return err
}

When it happens

Trigger: Calling DeleteLTXFiles or DeleteAll on an oss/azure-backed replica where the batch delete API returns per-key errors (missing objects, permission failures, throttling) — deleteResultError builds the message from the failed key list.

Common situations: Retaining/purging old LTX files whose blobs were already removed by an Azure lifecycle policy; SAS token or account key lacking delete permission on the container; transient 429/5xx responses during bulk cleanup.

Related errors

• failed to delete files:
• abs: cannot delete ltx file %q: %w
• abs: cannot delete blob %q: %w
• bucket required for abs replica URL
• abs: container name is required

AI-assisted analysis of benbjohnson/litestream@4ed7a308f6 (2026-09-06). Data as JSON: /api/errors/81a4afdbe576fd3b. Report an issue: GitHub.