DirectoryBackup API·续

DirectoryRestoreOptions

  • dir string optional — absolute path of the directory to replace. The default is dir from the record.
  • signal AbortSignal optional — cancels the operation. Refer to Cancellation.

DirectoryBackupDeleteOptions

  • signal AbortSignal optional — an aborted signal rejects the call before the object is deleted.

An option that a method does not accept, or an option of the wrong type, throws TypeError.

What a backup contains

backup() walks dir without following symbolic links and does not enter other filesystems. A mount point inside dir becomes an empty directory in the backup. restore() works the other way: it refuses a target that contains a mount point. For more information, refer to restore. backup() includes every other path, including .git, unless exclude or gitignore leaves it out.

A backup keeps:

  • File contents
  • Directories, including empty ones
  • Symbolic links, as links
  • Hard links between files inside dir
  • Permission bits, and numeric user and group IDs
  • Modification times, to the nanosecond

A backup does not keep:

  • Sockets, devices, and FIFOs
  • The setuid and setgid bits
  • Extended attributes, ACLs, and file capabilities
  • Holes in sparse files, which restore as zeros
  • Access times

When the image user is root, restore() sets the saved user and group IDs as numbers, even when the image has no user with that ID. Otherwise, the restored files belong to the image user.

Operations in one container

One backup() or restore() runs at a time in a container. Other calls wait for it to finish, including calls from other DirectoryBackup instances and from a Durable Object that restarted. Promise.all() over several directories runs them one after another. delete() does not wait.

Cancellation

DirectoryBackup sets no timeouts and does not retry. Aborting signal rejects the call with the abort reason without waiting for the helper process, including a call that is still waiting for another operation. The helper process in the container then removes what the operation created and exits.

After restore() verifies the download, it finishes replacing the target even if signal aborts. The call then resolves when the target is replaced, or rejects with the error from replacing it.

When the Durable Object restarts during an operation, the result of the call is lost, and the helper process exits. A backup is not recorded. A restore has either replaced the whole target or left it as it was. Restoring the same backup again gives the same result either way.

DirectoryBackupGateway

DirectoryBackupGateway is a WorkerEntrypoint that moves backups between the container and the R2 bucket.

  • The container can reach only the object of the operation in progress. During a backup, it uploads parts of that object. During a restore, it reads byte ranges of it. It cannot list or delete objects or reach another key.
  • The SHA-256 check detects an object that changed after the backup.

The container sends HTTP requests to the gateway at backups.sandbox.internal, which DirectoryBackup routes with interceptOutboundHttp(). The Durable Object creates, completes, and aborts uploads, and deletes objects, through RPC calls to the gateway. The first operation in a container, or intercept(), adds the intercept target. Each later operation replaces the handler on that target and does not add a target.

Limits

The container uploads the compressed backup in parts of 16 MiB. An R2 multipart upload holds up to 10,000 parts, so a compressed backup can be at most 160,000 MiB, about 156 GiB. A larger backup fails with BACKUP_TRANSFER.

Local development

Under wrangler dev, the container runs in Docker, and restore() cannot replace a directory that is part of the image. The restore fails with SandboxFileError code EXDEV and leaves the directory as it was. restore() can replace a directory that was created after the container started, a directory in a volume, or a target that does not exist yet.

Errors

SandboxBackupError

The backup object is missing, changed, or could not be transferred.

Field Type Description
name "SandboxBackupError" Error name
code SandboxBackupErrorCode Error code
operation DirectoryBackupOperation Method that failed: backup or restore
path string Directory being backed up or restored
detail string Error description

code is one of the following values:

Code Meaning
BACKUP_NOT_FOUND The object does not exist
BACKUP_INTEGRITY The object does not match the record, or it is not a valid archive. The target was not changed. backup() also throws it when R2 stored a different size than the container uploaded, and deletes the object
BACKUP_TRANSFER An upload or download between the container and DirectoryBackupGateway failed, including when storage.binding does not name an R2 bucket binding. detail contains the HTTP status. No record was returned, and no directory was changed

The package exports the SandboxBackupErrorCode and DirectoryBackupOperation types, which list these codes and methods.

SandboxBackupError is not a class. Use SandboxBackupError.is(error) instead of instanceof. It recognizes errors thrown in the same Worker and errors returned through Durable Object RPC.

SandboxFileError

Linux rejected the operation in the container. operation is backup or restore. Refer to SandboxFileError.

Code Condition
EBUSY The restore target is a mount point or has one inside it
EINVAL An exclude pattern is invalid
ENOENT dir from the backup or the parent of the restore target does not exist
ENOSPC The restore would fill the filesystem
ENOTDIR dir from the backup or the restore target is a symbolic link or is not a directory
EXDEV Linux could not swap the restored directory into place, as for a directory from the image under wrangler dev

Other codes, such as EACCES, come from reading a file during a backup.

SandboxProtocolError

DirectoryBackup could not complete its exchange with the helper binary. Refer to SandboxProtocolError.

Other errors

DirectoryBackup does not wrap errors from the runtime, from R2, or from its inputs.

Condition Error
Invalid options, record, or storage TypeError
storage.binding does not name an R2 bucket binding in backup() or delete() TypeError from DirectoryBackupGateway
The container is not running Error from exec()
signal is aborted The abort reason
R2 rejects creating, completing, or aborting an upload, or deleting an object The error from the R2 binding
An intercept cannot be added Error from interceptOutboundHttp()

Was this helpful?

YesNo

On this page

DirectoryBackup API·续 - 图1Docs

{"@context":"https://schema.org","@type":"TechArticle","@id":"https://developers.cloudflare.com/sandbox/reference/directory-backups/#page","headline":"DirectoryBackup API","description":"Reference for the DirectoryBackup class in @cloudflare/sandbox, which saves a directory from a running container to R2 and restores it.","url":"https://developers.cloudflare.com/sandbox/reference/directory-backups/","inLanguage":"en","image":"https://developers.cloudflare.com/sandbox/reference/directory-backups/og.png?v=477d2a7e03d74334","dateModified":"2026-10-22","publisher":{"@type":"Organization","name":"Cloudflare","description":"One platform for your apps, agents, and workforce. Build, secure, and scale without managing infrastructure","url":"https://www.cloudflare.com/","sameAs":["https://github.com/cloudflare","https://www.linkedin.com/company/cloudflare","https://x.com/cloudflare"],"logo":{"@type":"ImageObject","url":"https://developers.cloudflare.com/logo.svg"},"address":{"@type":"PostalAddress","streetAddress":"101 Townsend St","addressLocality":"San Francisco","addressRegion":"CA","postalCode":"94107","addressCountry":"US"},"contactPoint":[{"@type":"ContactPoint","contactType":"Customer Support","url":"https://support.cloudflare.com/","availableLanguage":["English"]},{"@type":"ContactPoint","contactType":"Sales","url":"https://www.cloudflare.com/contact/","availableLanguage":["English"]}]},"isPartOf":{"@type":"WebSite","@id":"https://developers.cloudflare.com/#website","name":"Cloudflare Docs","url":"https://developers.cloudflare.com/"}}

description: Reference for the Files class in @cloudflare/sandbox, which reads and writes files in a running container. title: Files API image: https://developers.cloudflare.com/sandbox/reference/files/og.png?v=41b41c52787424c4

Skip to content

Documentation Index
Fetch the complete documentation index at: https://developers.cloudflare.com/sandbox/llms.txt
Use this file to discover all available pages before exploring further.