In Rust, what does declaring pub enum PaymentError expose to downstream crates, and how should a variant wrap a dependency's error?
answer
- variants share the enum's visibility
- match, destructure, construct
- payload types join your API
- private field behind source()
basics
~20 sA pub enum makes every variant and every field public: callers can match, destructure and construct PaymentError, and each payload type joins your API. Keep a dependency's error out of it by storing it in a private field exposed only through source().
solid answer
~50 sRust gives enum variants and their fields the enum's own visibility; no field can be private, and `pub` on one is rejected with E0449, whose note says "enum variants and their fields always share the visibility of the enum they are in". So `pub enum PaymentError { Declined { code: u16 }, Network(io::Error), InvalidCard }` makes promises: callers may match each variant, read `code` as a `u16` and build their own `PaymentError::Network(...)`. Changing `code` to a `String`, or `Network`'s payload to another type, breaks them. If the payload is another crate's error type, that crate's type is now part of your API. The usual way to hide it is a variant holding your own struct, such as `NetworkError`, whose private field stores the cause as `Box<dyn Error + Send + Sync>` and exposes it only through `source()` — the opaque-struct approach `std::io::Error` takes with its public `ErrorKind`.
code
plaintext · 7 lineserror[E0449]: visibility qualifiers are not permitted here
--> k.rs:1:36
|
1 | pub enum PaymentError { Declined { pub code: u16 } }
| ^^^ help: remove the qualifier
|
= note: enum variants and their fields always share the visibility of the enum they are ingo deeper
Recall that every variant and field of a pub enum is public: callers can read the fields, match the variants and build values of the enum themselves.
Explain the visibility rule and the E0449 rejection, then list what a public variant promises: its name, its field names and the exact field types.
Show you keep third-party error types out of public variants by wrapping them in an owned opaque struct, exposing causes through source() and details through accessors.
Weigh enum versus opaque struct per crate: a rich public enum helps callers branch but freezes representation, while io::Error's kind-plus-opaque split buys freedom at some ergonomics.
## Visibility of variants and fields Struct fields are private unless marked `pub`. Enum variants work differently: the Rust Reference lists them as one of the two exceptions to "private by default" — variants of a `pub enum` are public. Their fields follow too, and Rust gives you no way to change that. Try `pub enum PaymentError { Declined { pub code: u16 } }` and rustc 1.99.1 rejects the `pub` with E0449, "visibility qualifiers are not permitted here", adding the note "enum variants and their fields always share the visibility of the enum they are in". There is no private-field escape hatch inside a variant. ## What callers can do with a public error enum Given `pub enum PaymentError { Declined { code: u16 }, Network(std::io::Error), InvalidCard }`, downstream code may: - **Match every variant** and rely on the compiler to tell it when its match is incomplete. - **Destructure every field**, reading `code` as a `u16` and the `io::Error` as an `io::Error`, with all the methods those types offer. - **Construct any variant** — `PaymentError::Declined { code: 51 }` compiles in a caller's test or mock with no constructor function needed. - **Depend on the payload types' traits.** If `PaymentError` is `Send + Sync` today because its payloads are, callers may rely on that. Each of those is a promise. Changing `code` from `u16` to `u32`, renaming a variant, or swapping `Network(io::Error)` for some other payload breaks callers who used them, even when the variant's name and meaning are unchanged. Adding a variant is its own compatibility question, covered with API evolution and semantic versioning. ## The payload problem `std::io::Error` is a stable std type, so exposing it costs little. Exposing **another crate's** error type in a public variant is different: callers can name that type, match on it, and call its methods, so your crate's public API now includes it. When that crate releases a new major version with a changed error type, upgrading your dependency changes your public type too, and your release becomes a breaking one. ## Hiding a cause behind an opaque type The fix is to put a type you own in the variant and keep the dependency's error in a **private field** of it: ```rust pub struct NetworkError { source: Box<dyn Error + Send + Sync>, // private: callers cannot name the inner type } impl Error for NetworkError { fn source(&self) -> Option<&(dyn Error + 'static)> { Some(self.source.as_ref()) } } ``` Callers still match `PaymentError::Network(e)`, print `e`, and walk `e.source()` for diagnostics, but they cannot destructure or construct the inner value. You can change the HTTP or socket library underneath without touching the public type. If callers need a specific detail — a status code, a retry hint — add a method on `NetworkError` that returns it as a type you control. ## `std::io::Error` as the model `io::Error` itself is an opaque struct. Its representation (an OS error code, a bare kind, a custom boxed payload) stays private; callers branch on `kind()`, which returns the public `ErrorKind` enum, and reach a custom payload through accessor methods such as `get_ref()`, `get_mut()` and `into_inner()`. That split — a public enum for the decision, a private representation for everything else — is the pattern to copy when a single enum would expose too much. | Shape | Callers can | What you can change freely | |---|---|---| | `pub enum` with a dependency's type in a variant | match, destructure, construct, call the dependency's methods | almost nothing about that variant | | `pub enum` whose variant holds your opaque struct | match the variant, read your accessors, walk `source()` | the inner cause and its type | | opaque struct plus a public kind enum | branch on the kind, read accessors | the whole representation | ## Checklist for a public error enum 1. Give each variant only the data callers need to decide what to do. 2. Use your own types or std types in fields; keep third-party error types behind private fields. 3. Expose deeper causes through `source()`, not through public fields. 4. Remember callers can construct your variants, so do not treat a field's value as a guarantee that only your crate could have produced it.
- Why is `std::io::Error` an opaque struct with a `kind()` method rather than a public enum?Its representation — an OS error code, a bare `ErrorKind`, or a boxed custom payload — stays private, so callers cannot match or construct those internals. They branch on `kind()`, which returns the public `ErrorKind` enum, and reach a custom payload through accessors such as `get_ref()` and `into_inner()`.
- Is adding a fourth variant to a public `PaymentError` a compatible change?Not by default: any downstream `match` that lists every variant without a wildcard stops compiling with E0004. How a crate plans for future variants is a separate subject, covered with API evolution and semantic versioning; here the point is that the variant list itself is public.
- Fields of a pub enum's variants are private unless each is marked pub.
- A third-party error type inside a public variant is an internal detail.
- Callers can match on PaymentError variants but cannot construct them.
- Changing a variant's field from u16 to u32 is fine because the name stayed.
- Hiding a cause means dropping it rather than exposing it through source().