pub enum NbError {
Show 29 variants
CommandFailed {
command: String,
stderr: String,
exit_code: Option<i32>,
},
ExecutableNotFound {
path: String,
},
NotFound {
selector: String,
},
Io {
path: PathBuf,
source: IoError,
},
UnsupportedShowTarget {
selector: String,
actual_type: String,
},
DuplicateTitleHeading {
title: String,
heading: String,
},
ParseError {
kind: ParseErrorKind,
location: Range<usize>,
},
InvalidFingerprint {
reason: String,
},
JsonParseError {
source: String,
},
ValidationError {
reason: String,
location: Option<Range<usize>>,
},
UnsupportedDocumentFormat {
extension: String,
supported: Vec<String>,
},
GateTimeout {
gate: String,
timeout_ms: u64,
},
DirtyBaseline {
guidance: String,
},
PathCollision {
path: String,
plan_index: Option<u32>,
},
PathIgnored {
path: String,
guidance: String,
plan_index: Option<u32>,
},
PlanValidation {
kind: String,
message: String,
plan_index: Option<u32>,
},
IndeterminateCommit {
pre_revision: String,
post_revision_observed: Option<String>,
guidance: String,
},
RecoveryRequired {
pre_revision: String,
post_revision_observed: Option<String>,
status_observed: Option<String>,
preserved_paths: Option<Vec<String>>,
guidance: String,
},
FingerprintMismatch {
target: NoteTarget,
guidance: String,
},
AnchorMismatch {
target: String,
number: u32,
guidance: String,
},
OccurrenceMismatch {
expected: u32,
actual: u32,
},
OverlappingEdits {
indices: Vec<u32>,
},
InvalidLineWindow {
offset: u32,
limit: u32,
total_lines: u32,
},
EmptySubstringPattern,
FragmentedBody {
fragment_count: u32,
guidance: String,
},
NonUtf8 {
selector: String,
path: String,
kind: String,
mime_hint: Option<String>,
},
IndexLockTimeout {
path: String,
timeout_ms: u64,
},
UnsupportedStructure {
reason: String,
},
WrongKind {
expected: KindSet,
actual: EntityKind,
selector: String,
path: String,
},
}Expand description
Errors raised by nb-api operations.
All variants are serializable so they can traverse MCP tool
response envelopes without lossy string flattening. The
std::error::Error implementation remains for ergonomic
interop with code that uses ? and standard error reporting.
std::error::Error is implemented MANUALLY below rather than
via thiserror::Error derive. The derive’s autodetect
treats any field named source as a #[source] chain link
and tries to convert it to dyn Error, which fails for
fields of type String (e.g., JsonParseError { source: String } per the P1 specification). The manual impl
preserves the field name and only sets a source-chain link
for variants whose source field is itself an Error.
Variants§
CommandFailed
An nb subprocess invocation failed (non-zero exit, or
spawning failed for a non-NotFound reason).
Fields
ExecutableNotFound
The nb executable could not be located on PATH (or in
the resolved location) when a subprocess was spawned.
NotFound
nb reported that the requested selector was not found.
Io
An I/O error occurred while accessing a notebook file or
the on-disk notebook directory. The source field captures
the original std::io::Error chain as a serializable
snapshot (recursive IoError).
Fields
UnsupportedShowTarget
nb show was invoked on a selector whose type is not
classified as text by nb itself (per the
add-0-2-0-foundation public-API spec). Folders, archives,
audio, video, image, and any other non-textual type reach
this path. The classification delegates to
nb show <selector> --type text so forward compatibility
is automatic when nb adds new textual types. Probe
failure (e.g., selector not found) does NOT route here;
it falls through to the original CommandFailed error
from the content-read path.
DuplicateTitleHeading
nb add was called with a title and content where the
first nonblank line of content is an exact Markdown ATX H1
duplicating the title. The validation runs in the caller
process before any subprocess invocation or notebook side
effect (including resolve_notebook); the rejection
happens entirely in-process. heading carries the exact
detected source line (including the leading # and any
surrounding whitespace) for actionable diagnostics. See
add-0-2-0-foundation public-API specification.
ParseError
A structural parse failure.
InvalidFingerprint
A fingerprint string failed structural validation (wrong
prefix, wrong length, mixed case, etc.). reason carries a
machine-readable category (e.g., "empty",
"unknown_algorithm_prefix", "uppercase_hex").
JsonParseError
JSON deserialization failed when constructing a typed
wrapper (e.g., crate::fingerprint::Fingerprint::from_json).
ValidationError
A semantic validation error raised by an operation boundary
(e.g., rejecting input that is structurally valid but
semantically illegal). location is None when the
failure is not byte-anchored.
UnsupportedDocumentFormat
Format-dispatch refusal (R3 revision).
parse(bytes, FromPath(path)) returned this error because
the final filename matched one of the recognized-but-
unsupported dotted suffixes (e.g., .org, .latex,
.tex, .adoc, .asciidoc). Format dispatch precedes
byte parsing, so no bytes were consumed and no
parse-error location is meaningful — this is a
contextual configuration error, not a parse failure.
extension carries the lowercase dotted suffix WITHOUT
the leading dot (e.g., "org", "latex").
supported is the owned canonical list of supported
extensions, populated at construction time from
crate::SUPPORTED_DOCUMENT_EXTENSIONS. The owned
Vec<String> shape is required for the derived
Serialize / Deserialize round-trip contract on
NbError.
GateTimeout
Process-shared gate queue wait exceeded. Notebook was not mutated.
DirtyBaseline
Transaction::commit refused because the notebook worktree/index is dirty.
PathCollision
Plan-op path collision against snapshot or earlier plan ops.
PathIgnored
Plan targets or would leave durable state on a Git-ignored path in a way that cannot be represented in the single checkpoint (existing ignored entry mutation), or requires force-staging (reported only when force-stage is unavailable). Prefer rejecting existing-ignored mutators.
PlanValidation
Validation/apply failure tied to a plan entry.
IndeterminateCommit
Commit completion is unknown (e.g. transport timeout after checkpoint may have started).
RecoveryRequired
Cleanup after a known failed apply could not verify clean pre_revision.
Fields
FingerprintMismatch
Body fingerprint precondition failed.
AnchorMismatch
Line number/anchor precondition failed.
OccurrenceMismatch
Substring expected_count did not match actual matches.
OverlappingEdits
Overlapping line edits in one batch.
InvalidLineWindow
Invalid show_note_lines window.
EmptySubstringPattern
Empty substring pattern refused at enqueue/apply.
FragmentedBody
Contiguous-body-only op invoked on a multi-fragment document.
NonUtf8
Structured text surface hit non-UTF-8 bytes in a text-classified file.
Non-textual notes keep using UnsupportedShowTarget; this variant
covers the narrow non-UTF-8-but-text case. Use
NbClient::read_note_source_bytes for raw access.
IndexLockTimeout
.nb-api-index.lock wait exceeded before any mutation.
UnsupportedStructure
Document structure is not supported for the requested op.
WrongKind
An operation was applied to an entity of the wrong kind:
deleting a folder as a note, editing text of a non-textual
file, or changing task state on a non-todo. Replaces
string-matched ValidationError / UnsupportedStructure
reasons with typed kinds. expected is the accepted-kinds
set for the operation, actual the single observed kind.
Trait Implementations§
Source§impl<'de> Deserialize<'de> for NbError
impl<'de> Deserialize<'de> for NbError
Source§fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>where
__D: Deserializer<'de>,
fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>where
__D: Deserializer<'de>,
impl Eq for NbError
Source§impl Error for NbError
impl Error for NbError
Source§fn source(&self) -> Option<&(dyn Error + 'static)>
fn source(&self) -> Option<&(dyn Error + 'static)>
1.0.0 · Source§fn description(&self) -> &str
fn description(&self) -> &str
use the Display impl or to_string()