Problem
flows check refuses a step for declaring a model the step never declared —
one the resolver itself supplied as the default.
Observed on a flow whose agent steps set cli: claude and no model at
all, with a flows.json of {"cli": "claude"}:
RESOLVED step "review-semantics" cli "claude" model "claude-opus-5" from step
REFUSED [model_unknown] Step "review-semantics" declares model "claude-opus-5"
for CLI "claude", but it is not listed in project model registry
".../flows.json"; add the exact model only after verifying that project is
allowed to use it.
Both lines are about the same step in the same run. The resolver reports the
model as coming from step, but the spec has no model: key anywhere — the
value was defaulted. Then the registry check rejects that default.
So with no models key in flows.json, a flow that declares no model is
unrunnable, and the error blames the author for "declaring" something they did
not write.
Why it is hard to act on
- The message says "add the exact model only after verifying that project is
allowed to use it." A reader who wrote no model has to first work out
which model is being complained about, and that it came from a default.
RESOLVED ... from step is inaccurate for a defaulted value. from default
(or from cli default) would make the situation legible immediately.
- The same spec passed
flows check on another machine with the same
flows.json, which suggests the enforcement is version-dependent. A spec
that validates on a developer's laptop and refuses on the host it will run on
is the worst place for this to surface.
Proposals, any of which would resolve it
- Do not apply the registry check to a value the resolver defaulted. The
registry exists to stop a flow author from naming a model the project is not
allowed to use. A default the tool chose is not that.
- If the check must apply, say so precisely: "no model was declared; the
default for CLI claude is claude-opus-5, which is not in the project
model registry. Add it to models in flows.json, or set an allowed model on
the step."
- Report the true source in the
RESOLVED line — from default rather
than from step — so the two lines stop contradicting each other.
Workaround, and why it is unpleasant
Adding "models": ["claude-opus-5"] to flows.json fixes it, but flows.json
is usually a tracked file. On a run whose whole purpose was to verify that
nothing modified the repository, the only way to start was to dirty a tracked
file first — which then had to be excluded from the run's own
did-anything-change check.
Problem
flows checkrefuses a step for declaring a model the step never declared —one the resolver itself supplied as the default.
Observed on a flow whose agent steps set
cli: claudeand nomodelatall, with a
flows.jsonof{"cli": "claude"}:Both lines are about the same step in the same run. The resolver reports the
model as coming
from step, but the spec has nomodel:key anywhere — thevalue was defaulted. Then the registry check rejects that default.
So with no
modelskey inflows.json, a flow that declares no model isunrunnable, and the error blames the author for "declaring" something they did
not write.
Why it is hard to act on
allowed to use it." A reader who wrote no model has to first work out
which model is being complained about, and that it came from a default.
RESOLVED ... from stepis inaccurate for a defaulted value.from default(or
from cli default) would make the situation legible immediately.flows checkon another machine with the sameflows.json, which suggests the enforcement is version-dependent. A specthat validates on a developer's laptop and refuses on the host it will run on
is the worst place for this to surface.
Proposals, any of which would resolve it
registry exists to stop a flow author from naming a model the project is not
allowed to use. A default the tool chose is not that.
default for CLI
claudeisclaude-opus-5, which is not in the projectmodel registry. Add it to
modelsin flows.json, or set an allowed model onthe step."
RESOLVEDline —from defaultratherthan
from step— so the two lines stop contradicting each other.Workaround, and why it is unpleasant
Adding
"models": ["claude-opus-5"]toflows.jsonfixes it, butflows.jsonis usually a tracked file. On a run whose whole purpose was to verify that
nothing modified the repository, the only way to start was to dirty a tracked
file first — which then had to be excluded from the run's own
did-anything-change check.