Troubleshooting

Start with the failing command, config path, run name, and first error. Save the run’s records before restarting. check --no-probe inspects configuration and component loading; the ordinary check also runs one task and can make paid calls.

Symptom	Inspect first	Action
hermit not found	Active Python environment	Activate it and run python -m pip install -e .; verify hermit --help
Unknown key or wrong file path	Config spelling and config directory	Compare the field reference; resolve paths relative to the YAML
Template not found	template and its adapter.yaml	Use a registered id such as prompt-only@1.0 or a directory containing the manifest
GEPA/SkillOpt cannot import	Installed requirements and environment	Install requirements-gepa.txt or requirements-skillopt.txt in the environment running the CLI
Learner authentication fails	Learner endpoint, key variable, backend CLI	Verify the configured variable is set without printing it; authenticate the selected CLI
train refuses to start: ... serves [...], not 'responses' (or 'messages')	The model’s backend and the caller’s dialect	Codex speaks the Responses API only, Claude Code the Messages API only: bind a backend that serves it (vLLM, SGLang, Fireworks, DeepSeek) or a translating proxy; hermit backends check <ref> tries each dialect. See Model backends
Actor works but learner fails, or conversely	Separate actor/learner configurations	The pipeline owns acting-model settings; llm and backend parameters own learner settings
bwrap missing or namespace denied	Linux runtime and namespace policy	Install bubblewrap and use an environment permitting its namespaces; see Installation
Probe fails on adapter=None	Pipeline’s baseline branch	Make no-adapter execution valid; do not assume every call has an adapter directory
Invalid split or no test tasks	Task ids and split files	Ensure ids exist and splits are disjoint; eval requires a nonempty test split
Adapter remains unchanged	Learner status, feedback, learnable paths	Read the step report; a valid no-op, perfect batch, rejected candidate, or validation gate can explain it
Unexpected files disappear	Specification-check issues	Add intended paths to a new template’s learnable rules before training
Score does not rise after an update	Timing and held-out results	The current step’s score precedes its update; inspect the next rollout and separate evaluation
Budget seems too low or unknown	Usage reporting and model prices	Include external calls and candidate tests; unknown cost is not zero
Timeout at epoch end	SkillOpt slow update or long agent session	Inspect method work and align per-session and Trainer timeouts
Run already finished	summary.json	Choose a new run name; do not expect a completed run to resume
Wrong run evaluated	Run-name/output overrides	Use the same overrides on train and eval; inspect the returned commit
Plugin conversion refuses context or roles	Target capability and omitted report	Use a supported host or workspace deployment; use --allow-lossy only if omitting those exports is intended
Host cannot find adapter tools	Generated command, Python, source directory	Keep workspace deployment’s source paths available; check the host’s MCP logs and tool imports
Streaming result differs from an aggregate eval	Window order and checkpoint selection	Use the recipe’s evaluator and benchmark metric

If training fails midway

Read steps.jsonl to find the last completed boundary, then inspect that step’s report and the process error. An Evolver failure can be recorded and training can continue with the previous adapter; a process crash may leave the run unfinished. Recovery explains which state is restored.

Do not infer rollback of an external database, service, or API charge from adapter rollback. Those belong to the task integration. Preserve evidence before deliberately restarting a stream.

If the run succeeds but performance is worse

Check that the pipeline loads the adapter it receives, the learner sees informative feedback, and the judge implements your intended objective. Compare none, root, and final under the same acting settings. Inspect raw task errors before changing the learning method. A specification check validates files rather than task quality; Evaluation covers a defensible comparison.

Reporting an issue

Include the framework commit/version, OS and Python version, method, command, config with credentials removed, first traceback, and relevant step status. A small task/pipeline/judge reproducer is more useful than an entire run. Review trajectories and feedback for private task content before sharing them.