Common problems

This page covers the messages and problems people run into most. Each heading is what Frost says, or what you notice.

#"Frost isn't set up yet, run frost init"

Frost can't find config.toml. Run frost init. If you use --config-dir or FROST_CONFIG_DIR, check it points at the right folder.

#"no key on this machine"

The key file is missing. If this computer already has storage set up, run frost key import and type your recovery phrase. Otherwise, run frost init.

#"a backup or restore operation is already in progress"

Another Frost process is using your backups, usually a scheduled backup. When it is one, Frost says "a scheduled backup is already running" and when it started. Wait for it to finish and try again. Deleting Frost's lock file doesn't stop the other process.

#"the local encryption key does not match"

Your storage holds backups made with a different key. Run frost key verify and type the phrase you wrote down to see which key it is. If it's the right one, run frost key import with it.

#Frost can't find your backups

Messages like "has no Frost repository" mean your backups aren't where Frost is looking. The error says where they were last opened and how to get back to them. See Moving your backups.

If your backups are gone from Permafrost while your access key still works, they were most likely deleted using that key. Email care@getfro.st straight away. If someone else might have your key, get a new one at getfro.st/perma/recover.

#Setup can't connect

Setup explains the problem and goes back to the answer most likely to blame.

#"This storage provider does not support conditional writes"

Your storage doesn't support a feature Frost needs to keep computers from overwriting each other's backup records. Different keys or settings won't fix it. Choose other storage. See Choosing storage.

A self-hosted server or a drive says it differently. The server "cannot create hard links", or the folder is "on an unsupported filesystem". Use a folder on a filesystem like ext4, Btrfs, XFS, ZFS, APFS or NTFS.

#"the server didn't accept Frost's SSH key"

Your self-hosted server refused Frost's key, for example after the key was removed from authorized_keys. Run frost init and add the key again. See Self-hosted.

#"the server's SSH host key has changed"

Frost refuses to connect when the server's identity changes, the same as ssh does. If you reinstalled the server or it got a new address, remove its old key with ssh-keygen -R <host> and run frost init again. Otherwise, find out why the key changed before you connect.

#"... not found. Connect the required drive and try again"

Your backups are on a drive that isn't connected, or the folder's path changed. Connect the drive. If Windows gave it another letter, see Local drive.

#"the Permafrost access key was rejected"

The message goes on with Permafrost's reason: the key is wrong, a newer key replaced it, or the account closed. Use your newest key, or get a new one. See Permafrost.

#"uploads are paused"

Permafrost isn't accepting new backups for your account right now. The message says why and until when, and restores keep working. See Permafrost.

#A backup can't read a folder

On macOS, this is usually a privacy permission. The error says what to allow. See macOS permissions. On other systems, check that your user can read the folder.

#Files listed as "couldn't be read"

Frost skipped those files and saved the rest. Common causes are files you don't have permission to read, files deleted during the backup, and, on macOS, files that iCloud keeps only online.

#Files that "continued changing while being read"

A program was writing to those files during the backup, so the snapshot kept their previous copy. Close the program and back up again, or let the next backup pick them up.

#A folder is "not found"

A folder on your list wasn't there, so Frost backed up the rest. Plug the drive back in, or if the folder moved, update your list with frost init.

#"config.toml changed, but updating the scheduled job failed"

You edited config.toml, and Frost couldn't update the scheduled job to match. The rest of the message says why. If it names a setting, fix it in config.toml. Frost tries again with every command until it works.

#"config.toml changed where backups go"

You changed where backups go in config.toml, and Frost found a problem with the new location the first time it used it. The rest of the message says what. See Moving your backups.

#"scheduled job is missing"

The scheduled job was deleted or switched off. Put it back with frost config set schedule.enabled true.

#Scheduled backups don't run

• Check the "next backup" row in frost status.
• On macOS, check Frost's switch in System Settings > General > Login Items & Extensions. It's listed as Node.js Foundation.
• On Windows, scheduled backups need you to be signed in, and don't run on battery power.
• With schedule.catch_up set to false, a backup due while the computer was off or asleep is skipped.
• Read the log. See Automatic backups.

#"verification failed"

A spot check found missing or damaged data in your storage. See Checking your backups.

#"cannot restore alongside original files"

The folder next to the originals isn't usable, often because the snapshot came from another computer. Use --to <dir> instead. See Restoring files.

#"cannot overwrite original files"

The snapshot came from a different kind of computer, or the path to the originals goes through a link Frost doesn't trust. Use --beside or --to <dir> instead.

#Restore says a file "changed after it was checked" or "has more than one link"

Frost found that a checked file changed, or that an unfinished restore file has a hardlink to another name. Stop programs that are changing the restore folder and retry. If an unfinished restore file is hardlinked, restore into a new empty folder instead.

#Frost can't find the snapshot you asked for

#Frost can't update itself

Frost's folder isn't writable, or Frost was built from source. See Updating Frost.

#The installer stops

#frost isn't found after installing

Open a new terminal. Terminals that were open while Frost installed don't see the new PATH. With pnpm, run pnpm setup once, then open a new terminal.