Optimization FAQ & fixes

In this page

This page covers common errors when starting, running, or reading an optimization, and how to fix them.

Common errors and fixes

Runs that won’t start or won’t stop

Symptom	Cause	Fix
The Run Optimization drawer shows a Run Prompt button instead of the run fields	The dataset has no column of generated outputs yet, so there’s nothing to optimize	Run a prompt against the dataset, then reopen the drawer
Starting the run is blocked with ‘Add evaluations before starting your optimization run’	Evals are the run’s objective; a run needs at least one to score against	Add an eval in the drawer’s evaluations section before clicking Start Optimization
The run is rejected with a ‘Missing required keys for optimizer …’ or ‘Unexpected keys provided for optimizer …’ error	Each optimizer accepts only its own exact set of parameters	Fill in only the fields the drawer shows for the optimizer you selected; see Optimizers for the exact parameter set per algorithm
A self-hosted deployment returns HTTP 402 when starting a run	Optimization is a paid feature, gated separately from the rest of the platform	Optimization needs to be enabled on your deployment; contact support to have it turned on
Stop isn’t on the run’s row	Stop only shows while a run is Queue or Running	There’s nothing to stop; if the run finished as Completed, check the trial list for its results

SDK

Symptom	Cause	Fix
GEPA raises an import or missing-library error from the SDK	gepa is a required dependency of agent-opt, so this points to an incomplete or broken install	Run pip install gepa, as the SDK’s ImportError message tells you; if that doesn’t resolve it, reinstall agent-opt (pip install --force-reinstall agent-opt)

Why a run failed or scores are flat

Failed before any trial ran

The run couldn’t be started, so it’s marked Failed immediately with no trials to open. The message on the run’s page is generic and just points you to contact support.

Failed partway through

The run failed after it had started. The run’s page shows a Failed to optimize panel with the error message from the point of failure; read it first to tell whether the run broke early, before any trial produced a usable score, or later on.

If the message points to your dataset or eval setup, check that the column being evaluated has a value for every row, or run the eval on its own outside optimization to see whether it fails the same way. If it points elsewhere, rebuild the run in the drawer to try again.

Scores didn’t improve across trials

Check your eval selection and your sample size: a trial is only as good as what it’s scored against, and every run samples at most 50 dataset rows, so a prompt that looks flat there may behave differently across the rest of your data. See A run scores at most 50 rows, and evals decide what counts as better for how each one shapes the score.

Still stuck? Reach out via support.

Keep exploring