duplicati/duplicati · error · UserInformationException

PrefixCannotContainHyphens

PrefixCannotContainHyphens

Error message

The prefix cannot contain hyphens (-)

What it means

Thrown by Controller.ValidateOptions when the backup --prefix is non-empty and contains a hyphen ('-'). Prefixes are used to build dblock/dlist/dindex filenames; hyphens would collide with Duplicati's internal filename delimiter parsing.

Source

Thrown at Duplicati/Library/Main/Controller.cs:978

            if (m_options.KeepVersions > 0)
            {
                selectedRetentionOptions.Add("keep-versions");
            }

            if (m_options.RetentionPolicy.Any())
            {
                selectedRetentionOptions.Add("retention-policy");
            }

            if (selectedRetentionOptions.Count() > 1)
            {
                throw new UserInformationException(string.Format("Setting multiple retention options ({0}) is not permitted",
                    string.Join(", ", selectedRetentionOptions.Select(x => "--" + x))), "MultipleRetentionOptionsNotSupported");
            }

            // Check Prefix
            if (!string.IsNullOrWhiteSpace(m_options.Prefix) && m_options.Prefix.Contains("-"))
                throw new UserInformationException("The prefix cannot contain hyphens (-)", "PrefixCannotContainHyphens");

            if (m_options.VolumeSize < m_options.Blocksize * 2)
                throw new UserInformationException("The volume size must be at least twice the block size", "VolumeSizeTooSmall");

            //Check validity of retention-policy option value
            try
            {
                foreach (var configEntry in m_options.RetentionPolicy)
                {
                    if (!configEntry.IsKeepAllVersions() && !configEntry.IsUnlimtedTimeframe() &&
                        configEntry.Interval >= configEntry.Timeframe)
                    {
                        throw new Interface.UserInformationException("An interval cannot be bigger than the timeframe it is in", "IntervalCannotBeBiggerThanTimeFrame");
                    }
                }
            }
            catch (Exception e) // simply reading the option value might also result in an exception due to incorrect formatting
            {

View on GitHub (pinned to 3f348be3e3)

Solutions

  1. Replace hyphens in the prefix with underscores or remove them.
  2. Leave --prefix unset to use the default prefix.
  3. If renaming, remember the prefix must match existing remote files or a new backup chain starts.

Example fix

// before: hyphen in prefix
--prefix=my-backup

// after: underscore instead
--prefix=my_backup
Defensive patterns

Strategy: validation

Validate before calling

if (!string.IsNullOrWhiteSpace(m_options.Prefix) && m_options.Prefix.Contains('-'))
    throw new ArgumentException("Prefix must not contain hyphens");

Try / catch

try { controller.BackupAsync(...); }
catch (UserInformationException ex) when (ex.HelpID == "PrefixCannotContainHyphens")
{ /* sanitize prefix and retry */ }

Prevention

When it happens

Trigger: Setting --prefix to a value containing '-' while the prefix is not blank.

Common situations: Using a descriptive prefix like 'my-backup'; appending a date or environment tag with hyphens; migrating from a tool that allowed hyphens.

Related errors

AI-assisted analysis of duplicati/duplicati@3f348be3e3 (2026-08-13). Data as JSON: /api/errors/cf2e286e99566e20. Report an issue: GitHub.