Error Handling
Errors fall into two groups: things Kit rejects the moment you call the method, and things only the platform can check, because they depend on your whole project, not just one object.
Kit-level errors
These throw immediately in your own code, with no CLI involved. Duplicate step IDs or names: 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' }));
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 when converted to a runtime workflow
const workflow = new Workflow({
id: 'broken-workflow',
name: 'Broken',
steps: [first], // 'second' is missing!
});
Invalid step parameters or credentials. new Step(...) validates type, required params (respecting conditional Applies when rules), and required credentials ({ name, id }) against the node catalog at construction time, throwing a TypeError immediately if a required field is missing or a credential provider name doesn't match what the node accepts.
Loop body rules. workflow.loop() throws immediately if its body callback doesn't return a core.loopOutput step, registers no steps, or attempts to add a trigger step inside the loop body.
Validated on sync and deploy
culvii dev and culvii deploy run the same validators, in the same order. Nothing is deploy-only: whatever would fail a deploy already failed your last dev sync, just earlier.
Invalid model configuration. An agent's model must be an object carrying a provider, a modelId, and a credentialId:
// Good
model: { provider: 'openai', modelId: 'gpt-4o', credentialId: 'my-openai-credential' }
// Bad: rejected, model must include a credentialId
model: 'openai/gpt-4o'
There's no env-var fallback, so a legacy '<provider>/<model-id>' string is rejected. Supported providers: openai, anthropic, gemini, vertexai, google-vertex.
Dangling cross-resource references. An agent referencing a workflow ID, a workflow referencing an agent or surface, that isn't defined anywhere in your project.
Duplicate reference keys. Every workflow, agent, and surface needs a unique slug; two resources can't share one.
Invalid surface definitions. A Surface that fails its own structural validation (see Surfaces overview).
Workflow tool trigger must be a manual trigger. A workflow wrapped with defineWorkflowTool() has to point triggerNodeName at a manualTrigger step; any other trigger type is rejected.
Nesting depth. A reference chain deeper than three nodes, or a leaf workflow/agent that owns something it shouldn't at that depth. A workflow invoked as a tool by a root agent (agent → workflow → agent) can contain a core.agent step as long as that nested agent does not itself define workflow tools; a workflow invoked as a tool by a workflow-invoked agent (workflow → agent → workflow) cannot contain a core.agent step.
Agent reference key. The agentReferenceKey on a core.agent step must match a defined MultiAgentEngine id (not agentId).
Secondary agent restrictions. Secondary agents cannot declare workflow tools, permissions, or networking (tools, permissions, and metadata.runtimeDetails.networking belong on the primary agent only).
Agent permissions, skills, and networking. On culvii dev sync and culvii deploy, the platform validates that maxIterations and maxToolCalls are positive integers, sandboxProfile is 'default', sandbox tool names in permissions.default are known or '*', and permissions.integrations entries use approved names with valid <resource> / <resource>.<operation> / '*' permission keys and a credentialId. For skills, sync and deploy validate the selection configuration (type: 'github_repository', HTTPS https://github.com/<owner>/<repo> URL up to 500 chars, credentialId matching ^[A-Za-z0-9_-]{1,128}$, ref up to 200 chars, relative source and fallback_paths up to 500 chars per path and 100 fallback paths, and no /skills/<repo-name> mount collisions across different repositories). At session start, the platform fetches each skill source from GitHub and rejects missing/inaccessible repositories or refs, trees over 10,000 entries, non-regular files (symlinks or submodules), missing or invalid SKILL.md YAML frontmatter (name matching ^[a-z0-9][a-z0-9-]{0,63}$ and description up to 1,024 chars), conflicting files across sources sharing a mount, or exceeding the 200 files per source, 8 MiB per source, 1 MiB per file, or 1 MiB catalog prompt limits. For networking, it rejects networking on a secondary agent, extra fields on unrestricted, or URLs, ports, paths, IPs, wildcards, or localhost/.local/.internal names in allowed_hosts.
Nesting depth. A reference chain deeper than three nodes, or a leaf workflow/agent that owns something it shouldn't at that depth. See Composing agents and workflows → How deep you can nest for the exact shapes.
Credential type mismatch. A step's supplied credential doesn't match the type its node expects — for example, a Slack credential wired into a GitHub step. Each credentialed node only accepts credentials for its own integration; see the node's own connector page for cases where more than one credential type is valid (for example, GitHub).
Quick reference
| Error | What to check |
|---|---|
| Duplicate step | Every step id and name is unique in the workflow. |
| Missing connection | Every connected step is included in the steps array. |
| Invalid step config | Required params and credentials: { name, id } match the node's definition. |
| Invalid loop body | workflow.loop() returns its core.loopOutput step and contains no trigger steps. |
| Invalid model | model is an object with provider, modelId, and credentialId. |
| Dangling reference | The workflow, agent, or surface you're referencing actually exists in your project. |
| Duplicate reference key | No two workflows, agents, or surfaces share a slug. |
| Workflow tool trigger | triggerNodeName names a manualTrigger step. |
| Nesting depth | The reference chain is at most three nodes, matching one of the two valid shapes. |
| Agent reference key | agentReferenceKey on a core.agent step matches a MultiAgentEngine id. |
| Secondary agent restrictions | tools, permissions, and metadata.runtimeDetails.networking are only declared on the primary agent. |
| Agent permissions, skills, and networking | Sandbox tool names are known, integration names and <resource> / <resource>.<operation> keys are valid, skill selections meet URL/path/credential/mount rules on sync/deploy and SKILL.md frontmatter plus 200-file / 8 MiB source / 1 MiB file / 1 MiB catalog limits at session start, and networking is valid (primary agent only, exact public hostnames in allowed_hosts). |
| Nesting depth | The reference chain is at most three nodes, matching one of the two valid shapes. |
| Credential type mismatch | The credential connected to this step is the right type for this node's integration. |