Error Handling

Most errors you encounter with the Culvii Kit will be definition errors. These happen when a workflow or agent configuration is invalid. The SDK catches these early, before execution begins, saving you from runtime surprises.

Duplicate steps

Workflow step IDs and names must be unique within a workflow.

workflow.addStep(new Step({ name: 'Prepare', type: 'core.set' }));
// This will throw an error:
workflow.addStep(new Step({ name: 'Prepare', type: 'core.set' }));

Why this matters: Unique names ensure that the engine can accurately track state, route data, and report logs for each specific step.

Missing connections

If you connect two steps, both must be explicitly added to the workflow's steps array.

const first = new Step({ name: 'First', type: 'manualTrigger' });
const second = new Step({ name: 'Second', type: 'core.set' });

first.connectTo(second);

// This will throw an error when converted to a runtime workflow
const workflow = new Workflow({
  name: 'Broken',
  steps: [first], // 'second' is missing!
});

Why this matters: The engine needs the full definition of every step in the execution path. If a step is missing, the workflow cannot execute past the connection point.

Invalid model names

Model strings must include the provider prefix.

// Good
model: 'openai/gpt-4o'

// Bad - will throw an error
model: 'gpt-4o'

Why this matters: The engine supports multiple providers (OpenAI, Anthropic, Gemini, etc.). The prefix tells the engine which API client and formatting rules to use.

Supported providers include: openai, anthropic, gemini, vertexai, and google-vertex.

Quick reference

Error	What to check
Duplicate step	Ensure every step id and name is unique in the workflow.
Missing connection	Verify every connected step is included in the steps array.
Invalid model	Check that the model string uses the <provider>/<model-id> format.
Unsupported provider	Ensure the provider prefix is spelled correctly and supported.