jdx/mise · error

invalid dotfile declaration {target} in {}

Error message

invalid dotfile declaration {target} in {}

What it means

During dotfiles preflight validation, each `[dotfiles.<target>]` entry in a config file must be parseable into a known declaration shape (whole-file entry or a managed line/block/template edit). If the TOML value cannot be parsed and it also does not look like a line/block/template/comment/position edit entry, mise rejects the whole config so nothing is silently dropped. This is a fail-fast guard so a typo never results in a partially applied dotfiles setup.

Source

Thrown at src/system/files.rs:557

                    && ["content", "block", "line", "template"]
                        .iter()
                        .any(|key| t.contains_key(*key))
            }) {
                bail!(
                    "encrypted dotfile {target} requires an external source, not inline content or edits"
                );
            }
            let Some(entry) = file_entry_from_toml(&target, value.clone()) else {
                // Managed line/block edits are handled by the edit engine,
                // not by this whole-file declaration parser.
                if value.as_table().is_some_and(|table| {
                    ["block", "line", "template", "comment", "position"]
                        .iter()
                        .any(|key| table.contains_key(*key))
                }) {
                    continue;
                }
                bail!("invalid dotfile declaration {target} in {}", path.display());
            };
            if let Some(table) = value.as_table() {
                for key in table.keys() {
                    if !matches!(
                        key.as_str(),
                        "source"
                            | "content"
                            | "mode"
                            | "exclude"
                            | "manifest"
                            | "autosave"
                            | "encrypt"
                            | "variants"
                            | "enabled"
                    ) {
                        bail!(
                            "unknown dotfile key {key:?} for {target} in {}",
                            path.display()

View on GitHub (pinned to afd2eddd3a)

Solutions

1. Check the entry in the config file named in the message; make it a valid dotfile table (e.g. source = "..." or content = "...").
2. If you meant a managed edit, include the `line` or `block` key (with `template`, `comment`, or `position` as needed) so the edit engine handles it.
3. Run `mise doctor` or the dotfiles status command to see which config file failed and fix its TOML syntax.
4. Verify the value parses as TOML (no stray quotes, correct = syntax) with a TOML linter.

Example fix

// before (mise config.toml)
[dotfiles."~/.vimrc"]
soruce = "vimrc"        # typo'd key, nothing parseable

// after
[dotfiles."~/.vimrc"]
source = "vimrc"

// run before apply: `mise doctor` or a TOML sanity pass
import toml from 'js-toml';
function assertDotfileEntry(cfg) {
  const v = cfg.dotfiles?.[target];
  if (typeof v !== 'string' && (typeof v !== 'object' || v === null))
    throw new Error(`${target}: not a valid dotfile declaration`);
  const editKeys = ['block','line','template','comment','position'];
  const known = ['source','content','mode','exclude','manifest','autosave','encrypt','variants','enabled'];
  if (typeof v === 'object' && !editKeys.some(k => k in v) && !known.some(k => k in v))
    throw new Error(`${target}: unparseable dotfile declaration`);
}

try {
  applyDotfiles();
} catch (e) {
  if (/invalid dotfile declaration/.test(e.message)) {
    console.error('Fix the dotfiles entry named in the message before re-running');
    process.exit(1);
  }
  throw e;
}

When it happens

Trigger: A `[dotfiles."~/.vimrc"]` entry whose value is not a table and not a string (e.g. a bare number or boolean), or a table that `file_entry_from_toml` cannot interpret (e.g. only unrecognized keys, wrong value types for `source`/`content`), while lacking any of the edit-engine keys `block`, `line`, `template`, `comment`, or `position`.

Common situations: Typos in the entry structure, writing the dotfile value as a scalar instead of a table/string, hand-merging config fragments that dropped required fields, or copying an edit-entry format from docs that uses different key names.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• unknown dotfile key {key:?} for {target} in {}
• dotfile {target}: inline content does not support mode, excl
• tracked file {target} cannot declare source, content, manife
• dotfile {target} cannot declare both source and content
• invalid manifest {manifest:?} for dotfile {target}

AI-assisted analysis of jdx/mise@afd2eddd3a (2026-09-09). Data as JSON: /api/errors/1a32e4b3bb94cbb1. Report an issue: GitHub.