HubPublic

Errors

Keep failure handling explicit

Use the same discipline in shell, CI, and Python: know whether the failure is invocation, validation, auth, registry state, or offline cache.

CLI validation and usage failures
  • rawctx.yaml not found: the package root is wrong or the manifest file is missing.
  • name must match "@scope/package": package refs stay lowercase and scope-qualified.
  • version must be a SemVer string (X.Y.Z): release numbers stay strict.
  • model file not found or file or directory not found: manifest paths do not resolve inside the package directory.
  • Unknown dataset(s): to_prompt() dataset filters do not match the loaded package.
Auth and registry failures
  • Authentication required. Run rawctx login first.: claim, publish, favorites, settings, or private access needs a token.
  • candidate package cannot be downloaded: candidate packages remain review-only until a published version exists.
  • version already exists: publish is idempotent on version numbers, so bump and retry.
  • Failed to reach registry or Download failed: remote request, network, or registry availability problem.
Python exceptions to catch
RawctxErrorUsageErrorAuthRequiredErrorRegistryErrorValidationErrorOfflineCacheMissError

Catch the narrow exception first when you can recover, then fall back to RawctxError when the worker should fail the step and surface the message.

Python

Recover by exception type instead of parsing message text

Use explicit exception classes when notebooks or services need to retry, log, or downgrade behavior.

import rawctx

try:
    model = rawctx.load("@pasar6987/stripe-subscriptions", offline=True)
except rawctx.OfflineCacheMissError:
    print("Snapshot is not cached yet. Retry online first.")
except rawctx.AuthRequiredError:
    print("Run rawctx login before using private or workspace-scoped access.")
except rawctx.ValidationError as exc:
    print(f"Package files are invalid: {exc}")
except rawctx.RegistryError as exc:
    print(f"Registry request failed: {exc}")
except rawctx.UsageError as exc:
    print(f"Invocation error: {exc}")

CLI exit behavior

Gate CI with non-zero failures only where the contract is intentional

Treat 0 as success and any non-zero exit as failure. When you want semantic changes to fail CI deliberately, use rawctx diff --exit-code-on ... instead of string-matching output.

set -euo pipefail

rawctx diff @scope/package@1.0.0 @scope/package@1.1.0 \
  --format github \
  --severity breaking \
  --exit-code-on breaking
Offline cache notes

search(), info(), snapshot_download(), and load() can all run offline only when package metadata or the extracted archive already exists in the local cache.

Click exit-path note

rawctx maps invocation problems onto Click's usage path and other runtime failures onto Click's exception path, so shell integrations should branch on success vs non-zero rather than hard-coding every numeric exit value.

Verification note

Package detail pages expose the published SHA-256 when the version metadata includes it. Use that checksum in release tooling today; the public CLI does not expose a dedicated checksum-verify flag yet.

Related docs

Move back to the happy path once the failure is classified

Most failures become easy once the boundary is clear: public Hub review, workspace auth, local validation, or registry reachability.

Open Python guideOpen workspace guideOpen CLI-first guide