Troubleshooting

Common problems and fixes, with the real error messages konareef prints. If you are unsure, run validate. It catches most issues offline.

Useful commands

konareef pod validate ./pod.toml     # offline schema check
konareef verify ./bundle             # re-verify a published bundle
konareef verify ./bundle --strict    # stricter signature/attestation checks
konareef smoke --token $KONAREEF_TOKEN   # end-to-end check against reef-core

Install problems

SymptomFix
command not found: konareef The binary is not on your PATH. Move it to a directory on PATH and restart your shell — see Install konareef.
go: ... requires go >= 1.25 Upgrade Go from go.dev/dl, then re-run go build -o konareef ..
ERR_SALT_STORAGE_UNAVAILABLE on pod init Your host has no usable OS keychain. This is normal on WSL, headless Linux, containers and CI. Every pod gets a salt at pod init. konareef does not store it in cleartext unless you ask. Set a passphrase: 
export KONAREEF_SALT_PASSPHRASE='choose-a-passphrase'
export KONAREEF_DISABLE_KEYCHAIN_BACKEND=1
Keep the passphrase. It encrypts your salt file. As a last resort, KONAREEF_ALLOW_PLAINTEXT_SALT=1 stores salts unencrypted on disk.
Keychain permission prompt on pod init (macOS) This is expected. The salt store uses your OS keychain. Allow access.

Validation problems

konareef pod validate reports each issue with a JSON pointer into the file. The exit code is non-zero on failure.

Unknown or misspelled field

./pod.toml: 1 validation issue(s)
 - pod: at '/pod': additional properties 'flavor' not allowed

Remove the extra key or fix the spelling. Most tables reject unknown fields — check the pod.toml reference.

Missing a required table

./pod.toml: 1 validation issue(s)
 - at '': missing property 'directive'

pod_spec_version, [pod], [runtime], and [directive] are all required.

Both task and template in [directive]

./pod.toml: 1 validation issue(s)
 - directive: at '/directive': 'oneOf' failed, subschemas 0, 1 matched

Provide exactly one of task (inline) or template (a file path).

Invalid pod name

./pod.toml: 1 validation issue(s)
 - pod.name: at '/pod/name': 'MyPod' does not match pattern '^[a-z][a-z0-9_-]*$'

Names must start with a lowercase letter and use only lowercase letters, digits, -, or _.

File path missing the ./ prefix

./pod.toml: 1 validation issue(s)
 - directive.template: at '/directive/template': 'prompts/system.md' does not match pattern '^\./'

In v0.1, every path is repo-relative and must start with ./ — e.g. ./prompts/system.md.

Publish & verify problems

SymptomFix
Verification reports a signature or attestation mismatch The bundle was altered or the publisher key does not match. Re-fetch the bundle. Confirm the publisher identity. Use konareef verify --strict to see the specific check that failed.
Disclosure-policy mismatch on verify Verify with the same policy the pod was published under: konareef verify ./bundle --disclosure-policy C (or D).
A mutating action is rejected as unauthorized Publishing and smoke checks need a session token — pass --token or set KONAREEF_TOKEN.

Errors you may see

When reef-core refuses a publish or a run, the CLI shows an error code. The table gives each code and its HTTP status, then what the code means and what to do. Two codes are not HTTP responses. They are the reason that a run stopped.

MeaningWhat to do
closed_pod_requires_cloud · 400 at publish
The pod is closed but does not set [runtime] execution_class = "cloud". A closed pod runs only on konareef infrastructure. Set execution_class = "cloud" and publish again. A closed pod cannot use local-mount.
closed_pod_requires_cloud · 422 at run
You asked to run a closed pod that does not declare execution_class = "cloud". The publisher must fix the manifest and publish a new version.
closed_pod_body_missing · 400 at publish
A closed publish did not include the encrypted body. Publish again with a konareef CLI that supports closed pods (v0.2.0 or later).
closed_pod_has_plaintext · 400 at publish
A closed publish also sent the body in clear text. Publish again with a konareef CLI that supports closed pods. Do not change the request by hand.
open_pod_has_body_fields · 400 at publish
An open publish sent encrypted-body fields. If you want to hide the body, set visibility = "closed" in [pod]. Otherwise, publish again without the encrypted-body fields.
publisher_not_allowed · 403 at publish or at listing
Both the publish endpoint and the listing endpoint can return this. On the private beta, only approved publishers can publish pods. Every beta user can run them. To publish on the beta, ask the person who invited you.
closed_pod_not_listed · 403 at run
That closed pod is not listed now, so it cannot run on the hosted service. Choose a listed pod, or ask the publisher to list this pod.
insufficient_credits · 402 at run
You have no credits left. reef-core checks credits only when a run starts. The credit check does not stop a run that has started. Ask the person who invited you for a top-up.
spawns_halted · 503 at run
The operator stopped new runs for a short time, for example for maintenance. Try again later.
budget_exceeds_cap · 422 at run
The max_sats in [budget] is more than the per-run ceiling. The operator sets this ceiling. The response gives the ceiling as cap. Set max_sats to the ceiling or less, then run again.
iterations_exceed_cap · 422 at run
The max_iterations in [directive] is more than the per-run ceiling. The operator sets this ceiling. The response gives the ceiling as cap. Set max_iterations to the ceiling or less, then run again.
budget_exhausted · 503 at run
The service used all of the total budget that the operator set. It cannot start new runs now. Try again later, or ask the person who invited you.
budget_exceeded · No HTTP status: the run's stop reason
The run reached its [budget] limit and stopped. A run can spend somewhat more than max_sats before it stops. A stopped run fails. Increase max_sats, decrease max_iterations, or use a less expensive model.
iterations_exceeded · No HTTP status: the run's stop reason
The run reached its max_iterations limit and stopped. A stopped run fails. Increase max_iterations, or make the task smaller.

Runtime & budget problems

SymptomFix
Run stops early with budget_exceeded The run reached its [budget] limit. Raise max_sats if appropriate, reduce max_iterations, or use a cheaper model.
reef-core rejects the runtime kind validate accepts any well-formed kind, but reef-core only runs registered runtimes (orca, lobster, …). Use one your deployment supports.
A secret is unavailable at spawn The named secret is not in the reef-core vault. Confirm the name in [dependencies].secrets matches a vault entry. konareef never stores secret values in the pod.
Still stuck?

Re-run konareef pod validate and compare against the pod.toml reference. Most runtime surprises trace back to a boundary declared in the manifest — budget, tools, or secrets.