astrid-runtime/astrid · error

unsupported legacy audit source {audit_source}; only the def

Error message

unsupported legacy audit source {audit_source}; only the default principal source is admitted

What it means

While scanning the legacy home for audit sources, the kernel found a directory it does not recognize. Only the default principal audit source can be migrated automatically; any other audit directory would need manual handling, so the migration aborts with AlreadyExists to force an explicit decision.

Source

Thrown at crates/astrid-kernel/src/lib.rs:4194

        let audit_source = local_root.join("audit");
        let audit_metadata = match std::fs::symlink_metadata(&audit_source) {
            Ok(metadata) => metadata,
            Err(error) if error.kind() == std::io::ErrorKind::NotFound => continue,
            Err(error) => return Err(error),
        };
        if audit_source == default_source {
            default_source_present = true;
            validate_audit_tree(&audit_source, audit_tree_device(&audit_metadata))?;
            continue;
        }
        if std::fs::read_dir(&audit_source)?
            .next()
            .transpose()?
            .is_none()
        {
            continue;
        }
        return Err(std::io::Error::new(
            std::io::ErrorKind::AlreadyExists,
            format!(
                "unsupported legacy audit source {}; only the default principal source is admitted",
                audit_source.display()
            ),
        ));
    }
    Ok(default_source_present)
}

/// Derived observer helper for optional post-cutover recertify.
/// Layout-2 boot and legacy cutover do not call this.
#[allow(dead_code, reason = "Refinery/observer recertify; not a boot gate")]
pub(crate) fn require_audit_integrity(
    results: &[(
        astrid_core::SessionId,
        astrid_audit::ChainVerificationResult,
    )],

View on GitHub (pinned to affd8760f4)

Solutions

  1. Identify the unrecognized audit directory and manually move it into migrations_dir/audit-principal-home.retired after verifying its contents
  2. Delete the stale audit directory if its data is no longer needed
  3. Check release/upgrade notes to map the legacy audit source name to its current equivalent

Example fix

// before: leftover legacy audit dir blocks migration
~/app/audit-old/
// after: retire it manually first
mv ~/app/audit-old ~/.app/migrations/audit-principal-home.retired
Defensive patterns

Strategy: validation

Validate before calling

// before migrating, ensure no unexpected audit dirs exist
fn unexpected_audit_sources(legacy_root: &std::path::Path, allowed: &std::path::Path) -> std::io::Result<Vec<std::path::PathBuf>> {
    Ok(std::fs::read_dir(legacy_root)?
        .filter_map(|e| e.ok())
        .map(|e| e.path())
        .filter(|p| p.file_name().map_or(false, |n| n.to_string_lossy().contains("audit")) && p != allowed)
        .collect())
}

Type guard

fn is_default_audit_source(p: &std::path::Path, expected: &std::path::Path) -> bool {
    p == expected
}

Try / catch

match run_migration() {
    Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists
        && e.to_string().contains("unsupported legacy audit source") => {
        // inspect and manually retire the unrecognized audit dir, then retry
    }
    r => r?,
}

Prevention

When it happens

Trigger: Running the legacy principal-home migration when an alternate/legacy audit source directory (from an older layout or a non-default principal id) exists alongside the default one.

Common situations: Upgrading from a very old version that used a different audit directory naming scheme; multiple principal profiles sharing one home; leftover directories from a previous aborted migration.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

AI-assisted analysis of astrid-runtime/astrid@affd8760f4 (2026-09-09). Data as JSON: /api/errors/168004d69da53ed4. Report an issue: GitHub.