Skryba
On this page

Runbook

Start from the first Error: line. Skryba exits 1 on every failure and preserves underlying causes below Caused by:.

No detector can run

no detector credentials found; configure GPTZERO_API_KEY, WINSTON_API_KEY, ORIGINALITY_API_KEY, or SAPLING_API_KEY

Set at least one non-empty key, or in Desktop put it in ~/.config/skryba/env and relaunch. If a specific list is required, put global --detectors before the subcommand.

--detectors must contain at least one detector name — remove an empty explicit list or supply names.

unknown detector "…"; available detectors: gptzero, originality, sapling, winston — correct the name.

<KEY> is required for <name> — an explicitly selected detector lacks its key.

Detector request or response failed

<name> request failed after retries — network/DNS/TLS connection failed after retries. Inspect the cause chain and configured *_API_URL.

<name> returned <status>: <body> — the provider rejected the request, rate-limited beyond retries, or remained unavailable. For 429/5xx, Skryba already retried; do not tight-loop.

<name> returned invalid JSON or response has no recognized probability in [0, 1] — provider response shape changed. Preserve the bounded response body and selected endpoint when reporting.

<name> cannot score empty text — provide non-whitespace input.

Cache failed

creating detector cache directory <path> — parent path cannot be created; fix ownership or select a writable --cache.

opening detector cache <path> — the file is unavailable, locked incompatibly, or corrupt. Preserve it before replacement if billing evidence matters.

detector cache lock poisoned — restart the process; a previous in-process panic poisoned the mutex.

Do not delete a cache casually: subsequent identical texts will be billed again.

Brama inference failed

BRAMA_TOKEN is required for Brama inference — set a non-empty client token.

SKRYBA_AGENT_ID and SKRYBA_AGENT_AUTH_SECRET must be configured together — set both or neither.

Brama request failed after retries — inspect reachability and BRAMA_URL.

Brama returned <status>: <body> — authentication, routing, model, or service failure returned by Brama.

invalid Brama JSON, Brama returned no message content, or Brama response was truncated at max_tokens — the completion is unusable; preserve the error and model name.

Rewrite or judge refused locally

  • input text cannot be empty
  • candidate count must be positive
  • maximum words per chunk must be positive
  • temperature must be between 0 and 2
  • minimum quality must be between 0 and 1

Correct the named value. Desktop controls already constrain candidates 1–32, chunk size 50–2,000, temperature 0.1–1.5, and quality 0.5–1.0.

quality judge failed to return a valid evaluation after three attempts — all three Brama replies failed JSON-boundary, schema, or [0,1] score validation. The nested cause says which.

Policy or training failed

reading policy <path> / parsing policy <path> — file missing, unreadable, or invalid JSON.

unsupported policy version …, policy vectors do not match the strategy count, policy contains a non-finite value — the policy is incompatible or corrupt; use a known version-1 file.

training requires at least one epoch and two generations per group — use --epochs >= 1 and --generations >= 2.

training reward weights and penalty are invalid — weights and penalty must be non-negative and detector plus quality weight must be positive.

unsupported training data extension "…"; use .json, .jsonl, or .txt — change the format or extension.

JSON training data must be an array, training row must be a string or object, training row has no non-empty text field, training data contains no text examples — correct the shape documented in train.

writing policy … / publishing policy … — make the output parent writable; check for a sibling .json.tmp left before rename.

Corpus and benchmark

curated corpus <path> contains no samples, curated sample <id> carries no text, or declared word/SHA mismatch — regenerate declarations from exact UTF-8 input; do not edit only the checksum to hide an accidental content change.

benchmark needs --corpus or at least one documentation root — supply one mode.

benchmark accepts either --corpus or documentation roots, never both — choose one.

benchmark sample and candidate counts must be positive, benchmark word bounds are invalid, or no qualifying passages found — correct numeric bounds or provide Markdown files with qualifying prose.

RentAHuman refused before network

Credential and URL:

  • RENTAHUMAN_API_KEY is required for RentAHuman
  • RENTAHUMAN_API_KEY contains invalid characters
  • RENTAHUMAN_API_URL is not a valid URL
  • RENTAHUMAN_API_URL must be an HTTPS base URL without credentials, query, or fragment

Request validation:

  • source text must contain 1 to 100000 characters
  • turnaround minutes must be between 5 and 10080
  • price cents must be between 300 and 100000000
  • idempotency key must contain 8 to 128 bytes
  • idempotency key cannot contain control characters
  • applicant screening source text cannot be empty
  • applicant screening percentage must be between 1 and 25
  • applicant screening maximum words must be between 50 and 500
  • language requirement cannot be empty
  • --language and --minimum-proficiency must be configured together
  • --screening-instructions-file requires --applicant-sample-file
  • humanization id contains invalid characters

Correct locally and rerun with the same idempotency key. RentAHuman returned <status>: <message> is an API refusal. RentAHuman request failed after retries is transport failure; retry the same create key. RentAHuman returned invalid JSON means no trustworthy order envelope was available—preserve the response context before retrying.

Maintained as part of the website-owned Skryba documentation corpus.