Errors and Troubleshooting

Both SDKs use a structured exception hierarchy rooted at MusherError. All SDK exceptions can be caught with a single base class, or you can handle specific error types for finer control.

Exception Hierarchy

Exception	When it's raised
`MusherError`	Base class for all SDK exceptions
`AuthenticationError`	No valid credential found, or the token was rejected by the registry
`BundleNotFoundError`	The bundle namespace/slug does not exist in the registry
`VersionNotFoundError`	The bundle exists, but no version matches the requested reference
`IntegrityError`	SHA-256 checksum mismatch during pull (includes `.expected` and `.actual` hashes)
`RegistryError`	The registry returned an unexpected error
`CacheError`	Failed to read or write the local cache
`RateLimitError`	Too many requests — retry after the indicated delay
`APIError`	General API error with RFC 9457 Problem Details fields

Error class	When it's thrown
`MusherError`	Base class for all SDK errors
`ApiError`	API returned an error response (carries `ProblemDetail`)
`AuthenticationError`	No valid credential found, or the token was rejected (extends `ApiError`)
`NotFoundError`	Bundle or version does not exist (extends `ApiError`)
`ForbiddenError`	Valid credential but insufficient permissions (extends `ApiError`)
`ValidationError`	Request payload failed server-side validation (extends `ApiError`)
`RateLimitError`	Too many requests (extends `ApiError`)
`NetworkError`	Connection or DNS resolution failure
`TimeoutError`	Request exceeded the configured timeout (extends `NetworkError`)
`CacheError`	Failed to read or write the local cache
`IntegrityError`	SHA-256 checksum mismatch (extends `CacheError`)
`SchemaError`	API response failed Zod schema validation
`BundleAssetNotFoundError`	Requested asset name does not exist in the bundle

Catching Errors

python

import musher
from musher import (
    AuthenticationError,
    BundleNotFoundError,
    IntegrityError,
    MusherError,
)

try:
    bundle = musher.pull("acme/code-review-kit")
except AuthenticationError:
    print("No valid API key found. Set MUSHER_API_KEY or run 'musher auth login'.")
except BundleNotFoundError:
    print("Bundle not found. Check the namespace and slug.")
except IntegrityError as e:
    print(f"Checksum mismatch: expected {e.expected}, got {e.actual}")
except MusherError as e:
    print(f"SDK error: {e}")

typescript

import { pull } from "@musher-dev/musher-sdk";
import {
  AuthenticationError,
  NotFoundError,
  IntegrityError,
  MusherError,
} from "@musher-dev/musher-sdk";

try {
  const bundle = await pull("acme/code-review-kit");
} catch (err) {
  if (err instanceof AuthenticationError) {
    console.error("No valid API key found. Set MUSHER_API_KEY.");
  } else if (err instanceof NotFoundError) {
    console.error("Bundle or version not found.");
  } else if (err instanceof IntegrityError) {
    console.error("SHA-256 checksum mismatch.");
  } else if (err instanceof MusherError) {
    console.error(`SDK error: ${err.message}`);
  } else {
    throw err;
  }
}

Common Scenarios

Authentication failures

If you see AuthenticationError, the SDK could not find a valid credential from any source. Check that:

MUSHER_API_KEY is set in your environment
The key starts with mush_ and has not been revoked
You have run musher auth login if relying on the keyring

Version resolution failures

In Python, VersionNotFoundError means the bundle exists but no published version matches your reference. In TypeScript, this surfaces as NotFoundError. Verify you are using a valid version constraint:

python

# Exact version
bundle = musher.pull("acme/code-review-kit:1.2.3")

# Semver range
bundle = musher.pull("acme/code-review-kit:^1.0")

# Latest
bundle = musher.pull("acme/code-review-kit")

typescript

// Exact version
const bundle = await pull("acme/code-review-kit:1.2.3");

// Semver range
const range = await pull("acme/code-review-kit:^1.0");

// Latest
const latest = await pull("acme/code-review-kit");

Integrity failures

IntegrityError indicates that a downloaded asset's SHA-256 checksum does not match the manifest. This can happen if:

The local cache is corrupted — clear it and retry
A network issue caused a partial download
The registry content was tampered with

Rate limiting

RateLimitError is raised when you exceed the registry's request limit. Both SDKs automatically retry with backoff. If you still hit limits, reduce request frequency or contact support.