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.

Runtime & budget problems

SymptomFix
Run stops early on budget_exhausted The pod hit its [budget] cap. Raise max_sats / per_call_cap_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.