Enum DepsError 

#[non_exhaustive]
pub enum DepsError {
    #[non_exhaustive]
    ParseError {
        file_type: String,
        source: Box<dyn Error + Send + Sync>,
    },
    RegistryError {
        package: RedactedUrl,
        source: SanitizedRegistryError,
    },
    CacheError(String),
    #[non_exhaustive]
    RateLimited {
        message: String,
        verified: RateLimitEvidence,
        source_status: Option<u16>,
    },
    PackageNotFound {
        package: RedactedName,
        registry: &'static str,
    },
    HttpStatus {
        url: RedactedUrl,
        status: u16,
    },
    ApiResponse {
        package: RedactedName,
        registry: &'static str,
        source: Error,
    },
    ResponseTooLarge {
        url: RedactedUrl,
        limit: usize,
    },
    InvalidVersionReq(String),
    InvalidPackageName(InvalidPackageName),
    Io(Error),
    Json(Error),
    UnsupportedEcosystem(String),
    AmbiguousEcosystem(String),
    InvalidUri(String),
    Offline {
        url: RedactedUrl,
    },
    ChainResolutionHalted,
}

Core error types for deps-lsp.

Extended from Phase 1 to support multiple ecosystems (Cargo, npm, PyPI). All errors provide structured error handling with source error tracking.

Examples

use deps_core::error::{DepsError, Result};

fn parse_file(content: &str, file_type: &str) -> Result<()> {
    // Parsing errors are automatically wrapped
    if content.is_empty() {
        return Err(DepsError::parse_error(
            file_type,
            &std::io::Error::new(std::io::ErrorKind::InvalidData, "empty content"),
        ));
    }
    Ok(())
}

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

#[non_exhaustive]

ParseError

A manifest or lockfile failed to parse.

#[non_exhaustive] on the variant itself (#1250, mirrors Self::RateLimited’s precedent): the only way to construct this from outside deps-core is Self::parse_error, which always routes source through crate::redact::parse_error_source — closing the recurring gap (#1240, #1243, #1249) where a new call site hand-built this variant with an unredacted source.

An external crate cannot build this variant as a struct literal — this fails to compile with E0639 (#[non_exhaustive] variant constructed outside its defining crate), not for some unrelated reason:

use deps_core::DepsError;

let _ = DepsError::ParseError {
    file_type: "Cargo.toml".into(),
    source: Box::new(std::io::Error::other("bad")),
};

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

file_type: String

Ecosystem/file kind being parsed (e.g. "Cargo.toml"), for the error message.

source: Box<dyn Error + Send + Sync>

The underlying parser error.

RegistryError

A registry HTTP request failed at the transport layer.

Fields

package: RedactedUrl

Name of the package the request was for — or, at several deps-core::cache call sites, the request URL instead (see RedactedUrl’s own docs). Redaction is safe to apply unconditionally: a genuine URL is redacted for real, and a genuine package name is left alone unless it happens to contain a : or a non-leading @ (a leading @, e.g. an npm-scoped name like @types/node, is left untouched), in which case it is redacted the same way a credential-bearing value would be (e.g. a Maven/Gradle group:artifact coordinate becomes group:***) — a cosmetic false positive, never a correctness issue, since no current call site populates this field with a coordinate (only cache.rs does, always with a URL).

source: SanitizedRegistryError

The underlying reqwest error, with its embedded request URL stripped.

CacheError(String)

The cache layer itself failed (e.g. a poisoned lock), independent of any registry request.

#[non_exhaustive]

RateLimited

A registry request was rejected for exceeding a rate limit. Unlike other variants, message is a pre-vetted, IP-free, actionable hint safe to surface verbatim in a per-dependency diagnostic (see Self::fetch_failure) — never build one from a raw registry error body, which can embed the caller’s public IP (github.rs:332-346).

#[non_exhaustive] on the variant itself (#1295 critic M1, added alongside verified): a future field addition to this variant specifically should not need to be a breaking change again — unlike the enum-level #[non_exhaustive] above, which only blocks an exhaustive top-level match on DepsError, not an exhaustive struct-literal pattern on this one variant’s own fields.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

message: String

Pre-vetted, IP-free message safe to surface verbatim in a diagnostic.

verified: RateLimitEvidence

Whether this classification is backed by explicit server evidence (e.g. a confirmed X-RateLimit-Remaining: 0 response header, checked in crate::cache) rather than merely inferred from a status code and request context alone (#1295). An unauthenticated GitHub 403 with no such evidence — which could be an abuse-detection false positive, a secondary rate limit, or an access-restricted repo — still gets classified as RateLimited for its actionable hint, but with verified: RateLimitEvidence::Inferred, so a caller like test_util::unwrap_or_skip_github_rate_limit can tell a confirmed exhaustion apart from an assumed one instead of silently treating both as the same expected case.

source_status: Option<u16>

The HTTP status this classification was built from, when known (#1295 critic N1). Some(403)/Some(429) for a crate::cache-classified confirmed rate limit — None for a canned, inference-only construction (e.g. crate::github::github_rate_limit_error) that never saw a live response. Exists so a caller like the authenticated pinned-tier cache-eviction guard (FR-015/ NFR-004, crate::cache) can restrict itself to a genuine 401/403 credential-rejection signal without also matching a 429 (mere throttling, not a credential-revocation signal) that happens to also classify as RateLimited.

PackageNotFound

A package name was not found on the given registry.

Fields

package: RedactedName

Name of the package that was looked up — stored redacted (#1209): the raw value is unreachable from this field’s type.

registry: &'static str

Name of the registry that reported the package as missing.

HttpStatus

A registry HTTP request returned a non-success status code.

Fields

url: RedactedUrl

URL that was requested — stored redacted (#789): the raw value is unreachable from this field’s type.

status: u16

HTTP status code returned.

ApiResponse

A registry’s response body failed to deserialize as JSON.

Fields

package: RedactedName

Name of the package whose response failed to parse — stored redacted (#1209): the raw value is unreachable from this field’s type.

registry: &'static str

Name of the registry the response came from.

source: Error

The underlying JSON deserialization error.

ResponseTooLarge

A response body exceeded the configured size cap and was rejected before full download.

Fields

url: RedactedUrl

URL the oversized response came from — stored redacted (#789): the raw value is unreachable from this field’s type.

limit: usize

The size cap, in bytes, that was exceeded.

InvalidVersionReq(String)

A malformed version-requirement string, for any ecosystem.

Previously also carried deps-go’s malformed-module-path rejections (#399 deferred that split); those now use Self::InvalidPackageName instead (#1514) — a module path is a package identifier, not a version requirement, and consumers that only expect version-requirement text (e.g. GoFormatter::validate_package_name) previously needed a documented unreachable!() arm to rule the version-requirement shape back out.

InvalidPackageName(InvalidPackageName)

A registry request’s target package/module name failed a structural validation gate (e.g. empty, oversized, or containing a ./.. path segment) — distinct from Self::InvalidVersionReq, which is for a malformed version-requirement string, not a malformed name. deps-go’s validate_module_path is the first caller (#1514).

Examples

use deps_core::{DepsError, InvalidPackageName};

let err: DepsError = InvalidPackageName::new("module path is empty").into();
assert!(matches!(err, DepsError::InvalidPackageName(_)));

Io(Error)

A filesystem I/O operation failed.

Json(Error)

A JSON parsing operation failed outside of a registry response context.

UnsupportedEcosystem(String)

The manifest file’s ecosystem could not be determined from any registered router.

AmbiguousEcosystem(String)

More than one ecosystem’s routing rules matched the same manifest path.

InvalidUri(String)

A URI supplied by the client or a manifest could not be parsed.

Offline

Returned by deps_core::cache::HttpCache’s 4 send sites (issue #483) when network.offline is set, instead of attempting the request. url is the request that was blocked, for diagnostic/logging purposes.

Fields

url: RedactedUrl

The request URL that was blocked — stored redacted (#789): the raw value is unreachable from this field’s type.

ChainResolutionHalted

A multi-hop alternate/private-index chain’s resolution was halted because a hop returned a genuine transport error (5xx, timeout, connection failure) rather than a clean “not found” — the chain deliberately does not fall through to a further, less trusted hop in this case (deps_pypi’s FR-005(c)/NFR-003(3), #513). Carries no arbitrary error text — mirrors Self::RateLimited’s pre-vetted-message precedent (see Self::fetch_failure’s security-load-bearing invariant) — so its classification there can safely be FetchFailure::Actionable with a fixed, safe message, surfacing this case in hover/diagnostics instead of only a tracing::warn!.

Implementations

impl DepsError

pub fn rate_limited( message: impl Into<String>, verified: RateLimitEvidence, ) -> Self

Constructs a Self::RateLimited error.

The only way to build this #[non_exhaustive] variant from outside this crate (#1295 critic M1: #[non_exhaustive] on the variant blocks a downstream crate’s struct literal, not just an exhaustive match) — an ecosystem crate with its own rate-limit classification distinct from crate::github’s (e.g. deps-gitlab-ci) uses this instead. message must be a pre-vetted, IP-free, actionable hint (see the variant’s own doc); verified should be RateLimitEvidence::Confirmed only when the caller has confirmed genuine exhaustion from explicit server evidence, not merely inferred it.

Examples

use deps_core::{DepsError, RateLimitEvidence};

let err = DepsError::rate_limited("set MY_TOKEN to increase the limit", RateLimitEvidence::Inferred);
assert!(matches!(err, DepsError::RateLimited { verified: RateLimitEvidence::Inferred, .. }));

pub fn parse_error(file_type: impl Into<String>, source: &dyn Display) -> Self

Constructs a Self::ParseError, routing source through crate::redact::parse_error_source so a credential-shaped parser error can never reach Debug/Display unredacted (#1250).

The only way to build this #[non_exhaustive] variant from outside this crate — mirrors Self::rate_limited’s precedent exactly.

Examples

use deps_core::DepsError;

let err = DepsError::parse_error("Cargo.toml", &"duplicate key: `serde`");
assert!(matches!(err, DepsError::ParseError { .. }));

pub const fn is_not_found(&self) -> bool

Returns true when this error means the registry was successfully asked and answered “this package doesn’t exist”, as opposed to the registry not having been answerable at all (network failure, timeout, malformed response, 5xx).

Distinguishing the two matters for diagnostics (#267): a genuine not-found is evidence the package name is wrong, while any other error is evidence only that this particular request failed — reporting the latter as “Unknown package” would mislabel a transient registry outage as a nonexistent dependency. Covers DepsError::PackageNotFound (the ecosystems that map a 404 to it explicitly: npm, PyPI, Go, Swift) and a bare DepsError::HttpStatus with status == 404 (the ecosystems that propagate the raw HTTP status instead: Cargo, Maven, Gradle, Bundler, Dart, Composer, NuGet).

Examples

use deps_core::DepsError;

let not_found = DepsError::PackageNotFound {
    package: "left-pad".into(),
    registry: "npm",
};
assert!(not_found.is_not_found());

let http_404 = DepsError::HttpStatus {
    url: "https://crates.io/api/v1/crates/left-pad".into(),
    status: 404,
};
assert!(http_404.is_not_found());

let outage = DepsError::HttpStatus {
    url: "https://crates.io/api/v1/crates/serde".into(),
    status: 503,
};
assert!(!outage.is_not_found());

let cache_err = DepsError::CacheError("connection reset".into());
assert!(!cache_err.is_not_found());

pub fn fetch_failure(&self) -> FetchFailure

Classifies this error for the per-dependency “registry lookup failed” diagnostic (#478), distinguishing a failure with a safe, actionable hint to show the user from one whose raw text must never reach a diagnostic.

Security-load-bearing invariant: FetchFailure::Actionable is produced only from a fixed, pre-vetted, IP-free message — never by calling .to_string()/Display on an arbitrary DepsError to build one, since a raw HttpStatus or RegistryError body can embed the caller’s public IP (github.rs:332-346, exercised by the github crate’s test_parse_tags_page_github_rate_limit_returns_error).

Exhaustive by design, no wildcard arm (#1244 — the same bug class already fixed twice for CompletionContext (#793, #819) and designed against for EcosystemId (#118)): every current and future DepsError variant must be listed explicitly, so a new variant that should carry FetchFailure::Actionable guidance cannot silently fall through to FetchFailure::Transient just by being added after this match was written. #[non_exhaustive] on this enum does not block an exhaustive match here, since this method is defined in the same crate that declares the enum.

Examples

use deps_core::error::{DepsError, FetchFailure};
use deps_core::RateLimitEvidence;

let rate_limited = DepsError::rate_limited("set GITHUB_TOKEN", RateLimitEvidence::Confirmed);
assert_eq!(
    rate_limited.fetch_failure(),
    FetchFailure::Actionable("set GITHUB_TOKEN".into())
);

let other = DepsError::CacheError("connection reset".into());
assert_eq!(other.fetch_failure(), FetchFailure::Transient);

pub const fn is_offline(&self) -> bool

Returns true when this error means a request was blocked by network.offline (issue #483), as opposed to any other network or registry failure.

Used by deps_maven::registry to skip poisoning its negative-search-failure cache with an offline block, so toggling network.offline back to false takes effect immediately instead of being masked by RECENT_FAILURE_TTL.

Examples

use deps_core::DepsError;

let offline = DepsError::Offline { url: "https://crates.io/".into() };
assert!(offline.is_offline());

let other = DepsError::CacheError("connection reset".into());
assert!(!other.is_offline());

Trait Implementations

impl Debug for DepsError

Hand-written, not derived: originally because a derived Debug would have printed HttpStatus.url, Offline.url, ResponseTooLarge.url, and RegistryError.package raw and unredacted (#767 code-review follow-up) — any tracing::warn!(?err, ...)/{err:?} call site, a common and arguably more idiomatic alternative to %err, would have bypassed the hand-written Display text entirely and reintroduced the raw URL/query string. Since #789, those four fields are typed RedactedUrl directly, so a derived Debug would actually be safe too (each field’s own Debug already forwards to redacted text) — this impl is kept hand-written anyway as defense-in-depth against a future field-type regression, not because it is still load-bearing on its own. Every field is still shown (this is not a summary).

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for DepsError

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for DepsError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<Error> for DepsError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<Error> for DepsError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<InvalidPackageName> for DepsError

fn from(source: InvalidPackageName) -> Self

Converts to this type from the input type.