astrid-runtime/astrid · error

workspace capsule directory is redirected: {}

Error message

workspace capsule directory is redirected: {}

What it means

This error is thrown by `collect_from_capsules_dir` while scanning a workspace's capsules directory to collect marks. It fires when a directory entry inside the workspace capsules dir is a symlink (`symlink_metadata` reports `is_symlink()`), which the tool treats as a redirect of a capsule directory outside the workspace and refuses to process rather than silently following it.

Source

Thrown at crates/astrid-cli/src/commands/wit.rs:221

        }
        workspace.verify_tree("capsules")?;
    }

    Ok(marks)
}

/// Read WIT marks from explicitly selected workspace capsule metadata.
/// Principal installs are intentionally absent: their hashes come from the
/// authenticated daemon registry query above.
fn collect_from_capsules_dir(dir: &Path, marks: &mut HashSet<String>) -> anyhow::Result<()> {
    for entry in std::fs::read_dir(dir)
        .with_context(|| format!("failed to read workspace capsules: {}", dir.display()))?
    {
        let entry = entry?;
        let capsule_dir = entry.path();
        let metadata = std::fs::symlink_metadata(&capsule_dir)?;
        if metadata.file_type().is_symlink() {
            anyhow::bail!(
                "workspace capsule directory is redirected: {}",
                capsule_dir.display()
            );
        }
        if !metadata.is_dir() {
            continue;
        }
        astrid_core::platform_fs::verify_no_redirects(&capsule_dir)?;
        let meta_path = capsule_dir.join("meta.json");
        if std::fs::symlink_metadata(&meta_path).is_ok() {
            astrid_core::platform_fs::verify_no_redirects(&meta_path)?;
            if let Some(meta) = crate::commands::capsule::meta::read_meta(&capsule_dir) {
                marks.extend(meta.wit_files.into_values());
            }
        }
    }
    Ok(())
}

View on GitHub (pinned to affd8760f4)

Solutions

  1. Remove the symlink and place a real capsule directory at that path (e.g. copy or move the actual directory back into the workspace capsules dir).
  2. If the capsule was intentionally relocated, re-create the capsule in the workspace rather than linking to the external location.
  3. Check all entries with `ls -la` in the workspace capsules directory and replace every symlink with a real directory before rerunning the command.

Example fix

// before: capsule is a symlink pointing outside the workspace
ln -s ~/shared/my-capsule .astrid/capsules/my-capsule
// after: use a real directory in the workspace
cp -rL ~/shared/my-capsule .astrid/capsules/my-capsule
Defensive patterns

Strategy: validation

Validate before calling

for entry in std::fs::read_dir(capsules_dir)? {
    let p = entry?.path();
    if std::fs::symlink_metadata(&p)?.file_type().is_symlink() {
        eprintln!("skipping redirected capsule dir: {}", p.display());
        continue;
    }
}

Type guard

fn is_real_dir(p: &std::path::Path) -> bool {
    match std::fs::symlink_metadata(p) {
        Ok(m) => m.is_dir() && !m.file_type().is_symlink(),
        Err(_) => false,
    }
}

Try / catch

match collect_marks_in_workspace(dir) {
    Err(e) if e.to_string().contains("workspace capsule directory is redirected") => {
        eprintln!("fix the symlinked capsule dir before continuing: {e}");
    }
    other => other?,
}

Prevention

When it happens

Trigger: Running a workspace-level command (via `collect_marks_in_workspace`) when any entry in the workspace capsules directory (e.g. `.astrid/capsules/<name>`) is a symbolic link instead of a real directory.

Common situations: Developers symlink capsule dirs from elsewhere on disk to share code across workspaces, or a package manager / dotfiles setup replaced a real capsule directory with a symlink; moving capsules to another drive and leaving links behind also triggers it.

Understand the failure class

Background: Path traversal blocked: "path escapes the workspace" and "outside site root" errors when a path will not stay inside its allowed directory — this error's family across 26 libraries.

Related errors

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