| name | ovstorage-user-delete-safely |
| description | Use when removing objects safely, especially recursive directories or targets that need a dry-run first. |
| license | CC-BY-4.0 |
| version | 0.1.0 |
| author | NVIDIA Omniverse |
| tags | ["ovstorage","delete","safety"] |
| tools | ["Read"] |
| compatibility | Requires ovstorage MCP tools or equivalent library calls and an already-configured backend route. |
Delete Safely
Goal: Remove objects without losing data you didn't mean to lose.
When to use this: Cleaning up after a job, removing stale state,
or implementing user-initiated delete. Especially when the target is
a directory or you're not 100% sure what's underneath it.
Single-object delete
Removes one object. Low risk — there's exactly one thing to delete.
{
"tool": "ovstorage_delete",
"arguments": {
"address": "s3://my-bucket/temp/scratch.bin"
}
}
Successful response:
{"v": "0.1", "ok": true, "operation": "ovstorage_delete", "result": {"ok": true}}
Directory delete: always dry-run first
Recursive directory deletes are dangerous. The tool requires an
explicit dry_run parameter. Always run with dry_run: true first
and review the plan.
Step 1: dry-run
{
"tool": "ovstorage_delete_directory",
"arguments": {
"address": "s3://my-bucket/old-results/",
"recursive": true,
"dry_run": true
}
}
Response shows what would be deleted:
{
"v": "0.1",
"ok": true,
"operation": "ovstorage_delete_directory",
"result": {
"dry_run": true,
"would_delete_count": 47,
"would_delete_paths": [
"s3://my-bucket/old-results/run-001/output.json",
"s3://my-bucket/old-results/run-001/log.txt",
"..."
]
}
}
Read the count. Read enough of would_delete_paths to confirm the
shape matches your intent. If anything surprises you, stop.
Step 2: execute
If the plan is right, repeat the call with dry_run: false:
{
"tool": "ovstorage_delete_directory",
"arguments": {
"address": "s3://my-bucket/old-results/",
"recursive": true,
"dry_run": false
}
}
Response:
{
"v": "0.1",
"ok": true,
"operation": "ovstorage_delete_directory",
"result": {"dry_run": false, "deleted": true}
}
Non-recursive directory delete
If you just want to remove an empty directory marker:
{
"tool": "ovstorage_delete_directory",
"arguments": {
"address": "s3://my-bucket/empty/",
"recursive": false,
"dry_run": false
}
}
This fails with DirectoryNotEmpty if anything's underneath.
What NOT to do
- Don't skip the dry-run. Even for "just a temp folder" — the dry-run is 100ms of work to catch a mistake that's hours of work to recover from.
- Don't paginate past 100k entries. The tool caps dry-run enumeration at 100,000 entries. If your prefix has more than that, you've targeted the wrong prefix or you need to delete in batches.
- Don't pass
dry_run: false to "skip the confirmation." That's exactly what it does, and that's exactly the bug.
When things go wrong
error.code | Likely cause | What to do |
|---|
NotFound | Address doesn't exist | Already gone — your work here is done |
DirectoryNotEmpty | Non-recursive delete on a non-empty directory | Either drop the contents first, or use recursive: true (with dry-run!) |
PermissionDenied | Credentials can't delete | Check ovstorage_doctor |
Unsupported | Backend doesn't support delete | Rare — check ovstorage_capabilities for that prefix |
Internal | Dry-run found >100k entries — a fixed cap on one call, not a passing shortage, so retrying hits it again | Target a narrower prefix and delete in batches |
See also
