Introduction

Cargo workspaces organize multiple related crates into a single project with shared dependencies and a unified build. When a workspace member cannot be found, cargo build fails for the entire workspace. This happens when the members glob pattern in Cargo.toml does not match the actual directory structure, when a member crate's Cargo.toml is missing the [package] section, or when crates are added without updating the workspace configuration.

Symptoms

  • error: failed to load manifest for workspace member
  • could not find 'Cargo.toml' in '/path/to/crate'
  • package 'foo' is listed in workspace but not found
  • cargo check works for individual crate but not workspace
  • New crate added to directory but not recognized by workspace

Error output: `` error: failed to load manifest for workspace member /home/user/project/crates/api referenced by workspace at /home/user/project/Cargo.toml`

Caused by: failed to read /home/user/project/crates/api/Cargo.toml

Caused by: No such file or directory (os error 2) ```

Common Causes

  • members glob pattern does not match crate directory structure
  • New crate directory created without Cargo.toml
  • Cargo.toml in member crate missing [package] section
  • Member crate name in workspace does not match Cargo.toml name
  • Workspace in parent directory not updated when new crate added

Step-by-Step Fix

  1. 1.Verify workspace Cargo.toml members configuration:
  2. 2.```toml
  3. 3.# Root Cargo.toml
  4. 4.[workspace]
  5. 5.members = [
  6. 6."crates/core",
  7. 7."crates/api",
  8. 8."crates/cli",
  9. 9."crates/db",
  10. 10.]

# Or use glob pattern [workspace] members = ["crates/*"] # All directories directly under crates/ with a Cargo.toml are members ```

  1. 1.Check member crate has valid Cargo.toml:
  2. 2.```toml
  3. 3.# crates/api/Cargo.toml - MUST have [package] section
  4. 4.[package]
  5. 5.name = "myapp-api"
  6. 6.version = "0.1.0"
  7. 7.edition = "2021"

[dependencies] myapp-core = { path = "../core" } ```

Verify from workspace root: ```bash # List all workspace members cargo metadata --format-version 1 | jq '.packages[].name'

# Check if a specific crate is recognized cargo pkgid -p myapp-api # Should output: myapp-api#0.1.0 ```

  1. 1.Fix missing Cargo.toml for new crate:
  2. 2.```bash
  3. 3.# Create new crate with cargo
  4. 4.mkdir -p crates/new-feature
  5. 5.cd crates/new-feature
  6. 6.cargo init --lib --name myapp-new-feature

# Or with cargo-new-workspace cargo install cargo-new-workspace cargo new-workspace-feature new-feature

# Verify it is picked up by workspace cd ../.. cargo check -p myapp-new-feature ```

  1. 1.Resolve name mismatch between workspace and package:
  2. 2.```toml
  3. 3.# Root Cargo.toml references the directory
  4. 4.[workspace]
  5. 5.members = ["crates/database"]

# But crates/database/Cargo.toml has different name [package] name = "myapp-db" # This is fine - directory name != package name is OK

# However, when referencing as dependency, use the PACKAGE name: [dependencies] myapp-db = { path = "crates/database" } # path = directory, name = package ```

  1. 1.Exclude crates from workspace build:
  2. 2.```toml
  3. 3.[workspace]
  4. 4.members = ["crates/*"]

# Exclude crates that should not be built with the workspace exclude = [ "crates/experimental", # Not ready yet "crates/deprecated", # Being phased out ]

# These crates can still be built individually # cd crates/experimental && cargo build ```

  1. 1.Debug workspace resolution issues:
  2. 2.```bash
  3. 3.# Verbose workspace resolution
  4. 4.cargo build -vv 2>&1 | grep "workspace"

# Check workspace structure cargo tree --workspace

# Verify all members can be built for member in $(cargo metadata --format-version 1 | jq -r '.workspace_members[]'); do echo "Checking: $member" cargo check -p "$member" || echo "FAILED: $member" done

# Clean and rebuild workspace cargo clean cargo check --workspace ```

Prevention

  • Use glob patterns (crates/*) instead of explicit member lists
  • Add new crates with cargo init or cargo new in the correct directory
  • Run cargo check --workspace in CI to catch member issues early
  • Keep workspace Cargo.toml at the project root
  • Document the workspace structure in CONTRIBUTING.md
  • Use cargo install cargo-workspaces for workspace management commands