kopia/kopia · error

unknown mode

Error message

unknown mode %v

What it means

restoreOutput returns errors.Errorf("unknown mode %v", m) when the --mode flag value does not match any supported restore mode (local, zip, zip-no-compress, tar, tgz, or a value auto-detected to one of those). It is a guard against unsupported mode strings.

Solutions

1. Check `kopia restore --help` and use an exact supported mode: local, zip, zip-no-compress, tar, or tgz.
2. Fix the typo in the --mode flag value.
3. Use --mode auto (the default) to let Kopia detect the mode from the target path.
4. Upgrade Kopia if the mode you want was added in a newer release.

Example fix

// before
kopia restore --mode ziped kff82b1d... /tmp/out.zip
// after
kopia restore --mode zip kff82b1d... /tmp/out.zip

const VALID_MODES = ['auto', 'local', 'zip', 'zip-no-compress', 'tar', 'tgz'];
if (!VALID_MODES.includes(mode)) throw new Error(`invalid --mode '${mode}'; expected one of ${VALID_MODES.join(', ')}`);

try {
  await kopiaRestore({ mode, source, target });
} catch (err) {
  if (/unknown mode/.test(String(err))) {
    console.error(`Mode '${mode}' unsupported; use one of: local, zip, zip-no-compress, tar, tgz`);
  }
  throw err;
}

When it happens

Trigger: Passing an unrecognized --mode value to `kopia restore`, e.g. --mode ziped, --mode gzip, or a typo; detectRestoreMode passes through any non-"auto" value unvalidated.

Common situations: Typo in the --mode flag in a script or alias; copying a mode name from another backup tool (e.g. 'tgz2', 'zstd'); older Kopia version lacking a newer mode name.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• a snapshot time is needed to use a path as source
• action script file ( ) too long: , max allowed
• Cannot specify a 'point-in-time' option when creating a…
• Cannot specify a 'point-in-time' option when creating a…
• Cannot specify a 'point-in-time' option when creating a…

AI-assisted analysis of kopia/kopia@82495e54b5 (2026-09-07). Data as JSON: /api/errors/ddc8115af6436cb1. Report an issue: GitHub.

Appendix: source

Thrown at cli/command_restore.go:313

	case restoreModeTar:
		f, err := os.Create(targetpath) //nolint:gosec
		if err != nil {
			return nil, errors.Wrap(err, "unable to create output file")
		}

		return restore.NewTarOutput(f), nil

	case restoreModeTgz:
		f, err := os.Create(targetpath) //nolint:gosec
		if err != nil {
			return nil, errors.Wrap(err, "unable to create output file")
		}

		return restore.NewTarOutput(gzip.NewWriter(f)), nil

	default:
		return nil, errors.Errorf("unknown mode %v", m)
	}
}

func (c *commandRestore) detectRestoreMode(ctx context.Context, m, targetpath string) string {
	if m != "auto" {
		return m
	}

	switch {
	case strings.HasSuffix(targetpath, ".zip"):
		log(ctx).Infof("Restoring to a zip file (%v)...", targetpath)
		return restoreModeZip

	case strings.HasSuffix(targetpath, ".tar"):
		log(ctx).Infof("Restoring to an uncompressed tar file (%v)...", targetpath)
		return restoreModeTar

	case strings.HasSuffix(targetpath, ".tar.gz") || strings.HasSuffix(targetpath, ".tgz"):

View on GitHub (pinned to 82495e54b5)