Managed Service Diagnostics

Managed failures use the stable CLI error code CRAB-E0140 plus a more specific placement-free diagnostic in error.details.kind. The details never contain bucket names, physical prefixes, provider credentials, or tokens.

Confirm the CLI and locator

crab version
crab errors CRAB-E0140

The hosted locator must be exactly:

crab://crab.build/acme/models

It cannot contain an empty segment, extra path segment, user information, explicit port, query, or fragment. In particular, crab://crab.build//acme/models fails before authentication or storage access.

Confirm profile and live access

The most direct live check is an authenticated list request:

crab organization list --service crab.build --limit 1 --json

This validates the installed exact-authority profile, cached discovery, compatible API, token refresh, and service response. crab auth status reports the configured direct-provider token state; it is not a replacement for this managed-service probe.

If no profile is active, install and activate one:

crab login https://crab.build

For an enterprise authority, use the exact origin and configured CA trust from your administrator. Crab never probes arbitrary crab:// authorities to guess whether they are managed.

Inspect repository state

crab repo info acme/models --json

Only active repositories are cloneable and writable. A newly created repository may be provisioning; an archived repository is readable only where policy permits and is not writable; deleting, deleted, restoring, and failed states require the lifecycle action or operator remediation named by the service.

Read structured failures

Commands that support structured output write a standard error envelope and exit non-zero. Inspect both the stable code and managed kind:

if ! output=$(crab repo info acme/models --json 2>/dev/null); then
  printf '%s\n' "$output" | jq '{
    code: .error.code,
    category: .error.category,
    retryable: .error.retryable,
    kind: .error.details.kind,
    message: .error.message
  }'
fi

Only retry conditions that are explicitly marked retryable. A permission, profile, locator, or compatibility failure requires correction rather than a tight retry loop.

Protect diagnostic output

Use --log-level debug only when needed and keep diagnostic output in an access-controlled location. Crab redacts managed tokens and physical placement, but organization and repository logical names may still be sensitive business metadata. Never paste the one-time output from service-account creation or rotation into a support ticket.

For local repository checks, also use crab doctor, crab logs, and Structured Output. For HTTP status, headers, and stable service error codes, see the Managed Service API Reference.