Troubleshooting

Common problems and fixes, with the real error messages konareef prints. When in doubt, 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 ..

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 doesn’t 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 isn’t in the reef-core vault. Confirm the name in [dependencies].secrets matches a vault entry (values are never stored 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.