1. Symptoms
When you attempt to compile a Rust program containing a struct definition where one field directly references the struct type itself (outside of pointer wrappers), the compiler emits error E0640. The error message clearly indicates that the struct definition contains an unsupported self-referential pattern.
Shell output demonstrating the error looks like the following:
error[E0640]: self-referential struct
--> src/main.rs:5:5
|
5 | name: String,
6 | // ERROR: next points back to the containing struct
7 | next: Option<Node>,
| ^^^^^^^^^^^^^^ self-referential struct
|
= note: this error indicates that the struct is self-referential
= help: consider using `Box<Self>`, `Arc<Self>`, `Rc<Self>`, or a reference type
= help: for more information, see https://doc.rust-lang.org/reference/structures.html
A slightly different manifestation occurs when attempting to embed the struct directly within itself as a field rather than behind a smart pointer wrapper:
error[E0640]: self-referential struct
--> src/lib.rs:10:5
|
10 | tree: TreeNode,
| ^^^^^^^ self-referential struct
|
= help: consider using `Box<TreeNode>`, `Arc<TreeNode>`, or another indirection type
In more complex scenarios involving lifetime annotations, the error may appear alongside lifetime mismatch warnings:
error[E0640]: self-referential struct
--> src/processor.rs:15:9
|
15 | callback: Box<dyn Fn(&mut Self) + '_>,
| ^^^^^^^^^^^^^^^^^^^^^^ self-referential struct
The compiler consistently highlights the offending field and provides a hint suggesting the use of heap-allocated indirection types such as Box, Arc, Rc, or a reference type to resolve the issue.
2. Root Cause
Rust structs must have a statically known size at compile time. This requirement stems from the language’s memory layout guarantees and its zero-cost abstraction philosophy. When you define a struct field that directly contains the struct type itself, the compiler faces an impossible mathematical problem: computing the size of S requires knowing the size of S, which itself requires knowing the size of S, creating infinite recursion.
Consider a naive self-referential struct like the following:
struct Node {
value: i32,
next: Option<Node>, // What is the size of Node? It depends on Node, which depends on Node...
}
From the compiler’s perspective, Option<Node> contains a Node, which contains an Option<Node>, which contains a Node, ad infinitum. The compiler cannot allocate space for this struct because there is no finite upper bound on its size. Even though Option<T> has a known representation in Rust (it is typically the size of T plus one discriminant byte), the infinite regress makes the calculation unsolvable.
The fundamental issue is that Rust values must own their own data or borrow it through references. A struct field of type T means “this struct contains a T inline,” meaning T’s bytes are physically embedded within the struct’s memory layout. For this to work, T must have a known, finite size. The struct type itself obviously does not meet this criterion when it tries to contain itself directly.
This constraint is not arbitrary. Allowing self-referential structs inline would create severe problems including but not limited to: undefined behavior during moves (since the embedded pointer would point into memory that is being copied), inability to implement the Copy trait correctly, and memory unsafety when the struct is resized or reallocated. Rust’s type system prevents these footguns by rejecting self-referential structs at compile time.
3. Step-by-Step Fix
The fix for error E0640 involves introducing heap indirection through smart pointer types. Because Box<Node>, Arc<Node>, and Rc<Node> are all pointer types with known, fixed sizes (typically the size of a machine pointer, 8 bytes on 64-bit systems), they break the infinite recursion. The struct now contains a pointer to another struct of the same type rather than embedding the struct inline.
Before:
struct Node {
value: i32,
next: Option<Node>, // E0640: self-referential struct
}
After:
struct Node {
value: i32,
next: Option<Box<Node>>, // Fixed: Box<Node> has a known size
}
If you need shared ownership across multiple locations, use Rc<Node> for single-threaded scenarios or Arc<Node> for multi-threaded contexts:
Before:
struct TreeNode {
children: Vec<TreeNode>,
parent: Option<TreeNode>, // E0640: self-referential
}
After:
use std::rc::Rc;
use std::cell::RefCell;
struct TreeNode {
children: Vec<Rc<RefCell<TreeNode>>>,
parent: Option<Rc<RefCell<TreeNode>>>,
}
When you need interior mutability in addition to shared ownership, wrap the smart pointer with RefCell or Mutex depending on your threading requirements:
Before:
struct LinkedList {
head: Option<ListNode>,
}
struct ListNode {
data: i32,
next: Option<ListNode>,
}
After:
struct LinkedList {
head: Option<Box<ListNode>>,
}
struct ListNode {
data: i32,
next: Option<Box<ListNode>>,
}
If you genuinely need self-referential behavior with references rather than owned pointers, you can use a lifetime parameter to express the borrowing relationship. This requires careful lifetime management:
struct SelfRef<'a> {
value: String,
reference: Option<&'a str>,
}
However, structs with self-referential lifetime relationships are typically better handled through separate struct definitions or by restructuring your data model to avoid the self-reference altogether.
4. Verification
After applying the fix, compile your project to confirm that error E0640 no longer appears. Run the Rust compiler on the affected source file:
cargo build
A successful build produces no E0640 errors, and you should see the standard compilation output indicating success:
Compiling my_project v0.1.0 (path/to/my_project)
Finished dev [unoptimized + debuginfo] target(s))
If you introduced Rc or RefCell, write a small test to verify that the data structure behaves correctly:
#[cfg(test)]
mod tests {
use std::rc::Rc;
use std::cell::RefCell;
#[test]
fn test_linked_list_creation() {
let node = Node {
value: 42,
next: Some(Box::new(Node {
value: 100,
next: None,
})),
};
assert_eq!(node.value, 42);
assert!(node.next.is_some());
assert_eq!(node.next.as_ref().unwrap().value, 100);
}
#[test]
fn test_tree_with_shared_ownership() {
let child = Rc::new(RefCell::new(TreeNode {
children: vec![],
parent: None,
}));
let parent = Rc::new(RefCell::new(TreeNode {
children: vec![Rc::clone(&child)],
parent: None,
}));
// Update child's parent reference
child.borrow_mut().parent = Some(Rc::clone(&parent));
assert_eq!(parent.borrow().children.len(), 1);
assert!(child.borrow().parent.is_some());
}
}
Execute the test suite to confirm runtime correctness:
cargo test
All tests should pass without panics or borrow checker errors, confirming that your fix is semantically sound and not merely suppressing the compiler error through unsound patterns.
5. Common Pitfalls
One of the most frequent mistakes developers encounter when fixing E0640 is attempting to use Option<&Self> as a workaround without fully understanding lifetime constraints. While Option<&Self> technically has a known size (the size of a reference plus one byte for the discriminant), using it within the struct definition requires a lifetime parameter and restricts how the struct can be instantiated and moved.
// This will likely cause lifetime errors in practice
struct BadNode {
value: i32,
next: Option<&'static BadNode>, // Unusual and problematic
}
Another common pitfall involves forgetting that Box<T> implements Copy only when T: Copy, but Box<T> always implements Clone regardless of T’s properties. If your data structure needs to be cloneable, ensure you implement the Clone trait appropriately:
#[derive(Clone)]
struct Node {
value: i32,
next: Option<Box<Node>>,
}
Developers sometimes introduce unnecessary memory overhead by wrapping everything in Arc<Mutex<T>> when Rc<RefCell<T>> would suffice for single-threaded code. The Mutex wrapper carries synchronization overhead that is entirely unnecessary when your data structure never crosses thread boundaries. Always prefer the minimal indirection that satisfies your ownership requirements.
A subtler mistake occurs when using self-referential patterns with async code. Capturing self in an async block creates an implicit self-reference that can manifest as E0640 or similar errors. If you need to pass ownership of struct fields into async tasks, clone the necessary data explicitly rather than borrowing:
// Potentially problematic
async fn process(self: Arc<Self>) {
let data = self.data.clone(); // Clone the data, don't reference self
async_task(data).await;
}
Finally, when using Rc or Arc with RefCell, be vigilant about borrow checker violations at runtime. RefCell defers borrow checking to runtime, meaning you can panic if you violate the borrowing rules. For complex data structures, consider using RwLock or moving to a design that leverages Rust’s compile-time borrow checking wherever possible.
6. Related Errors
E0072: Recursive type has infinite size. This error is closely related to E0640 and often appears alongside it when dealing with recursive type definitions. E0072 is a more general error that covers any type whose size cannot be determined due to recursion, including trait objects and generic types that expand infinitely. The relationship is that E0640 is a specialized diagnostic for the specific case where the recursion involves the struct type itself, providing a more actionable hint about using Box, Arc, or Rc.
E0277: The trait bound X: Trait is not satisfied. This error can appear when you attempt to use a recursive struct with generics and the generic parameter does not satisfy the required trait bounds. For instance, if you define a recursive generic struct and try to use it in a context that requires Copy or Clone, E0277 may surface because your chosen smart pointer wrapper does not propagate those traits as expected.
E0509: Cannot move out of self because it is not Copy. This error manifests when you attempt to destructure a struct and take ownership of a field while leaving a reference behind. In the context of self-referential patterns, developers sometimes encounter E0509 when trying to manually implement methods that would effectively require moving fields out of a self-referential struct, which Rust’s borrow checker prohibits at compile time.