jdx/mise · error

managed system files require group '{group}', but that boots

Error message

managed system files require group '{group}', but that bootstrap group cannot be safely converged

What it means

This error is thrown when the referenced bootstrap group is known but its convergence plan is Unsafe/Unknown (ResourceAction::Unknown) while pending accounts are allowed. Because the library cannot guarantee the group will exist by the time files are managed, it refuses to proceed rather than risk assigning a nonexistent group. It is a stricter sibling of the 'absent' group error in the same match.

Source

Thrown at src/system/managed_files.rs:887

                }
                Some(_) if allow_pending_accounts => {}
                Some(_) | None => {
                    resolve_user(owner)?;
                }
            }
        }
        if let Some(group) = group {
            match accounts
                .and_then(|accounts| accounts.groups.iter().find(|request| request.name == group))
            {
                Some(request) if request.state == super::accounts::AccountState::Absent => bail!(
                    "managed system files require group '{group}', but that bootstrap group is absent"
                ),
                Some(request)
                    if allow_pending_accounts
                        && request.plan().action == ResourceAction::Unknown =>
                {
                    bail!(
                        "managed system files require group '{group}', but that bootstrap group cannot be safely converged"
                    )
                }
                Some(_) if allow_pending_accounts => {}
                Some(_) | None => {
                    resolve_group(group)?;
                }
            }
        }
    }
    Ok(())
}

#[cfg(not(unix))]
pub(crate) fn validate_principals(
    files: &[ManagedFileRequest],
    directories: &[ManagedDirectoryRequest],
    _accounts: Option<&super::accounts::AccountRequests>,

View on GitHub (pinned to afd2eddd3a)

Solutions

1. Make the group's plan deterministic (ensure its resource action resolves to a concrete Create/Update/None) before running file management.
2. Set allow_pending_accounts=false to force eager group resolution via resolve_group.
3. Reference a group whose plan is already known instead of the pending one.

Example fix

// before
manage_files(files, dirs, Some(&accounts), /*allow_pending_accounts*/ true)
// group 'deploy' plan action: Unknown

// after
resolve_accounts_blocking(&accounts)?; // make plan concrete
manage_files(files, dirs, Some(&accounts), /*allow_pending_accounts*/ false)

for g in files.iter().filter_map(|f| f.group.as_deref()) {
    if let Some(r) = accounts.groups.iter().find(|r| r.name == g) {
        if allow_pending && r.plan().action == ResourceAction::Unknown {
            return Err(format!("group {g} plan is not resolvable"));
        }
    }
}

fn group_plan_is_known(name: &str, accounts: &AccountRequests) -> bool {
    accounts.groups.iter().find(|r| r.name == name)
        .map_or(true, |r| r.plan().action != ResourceAction::Unknown)
}

When it happens

Trigger: Managed file entry references group `g`; AccountRequests contains `g` with plan().action == ResourceAction::Unknown and allow_pending_accounts is true. Typically happens when the group's creation is itself conditional/unresolvable at plan time.

Common situations: Group creation depends on an external provider whose action could not be planned; account requests come from a partially-evaluated config; plans involving pending/deferred account resources combined with managed system files.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• managed system files require group '{group}', but that boots
• only available on unix
• {} is not managed by [dotfiles]
• directory changed while restoring permissions: {}
• {}

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