Error reference

Mount API exceptions, API error handling, HTTP status codes, and Agent Spec validation errors in FlowDrop.

This page covers all error conditions you may encounter when integrating FlowDrop: mount exceptions, API errors during operation, and Agent Spec validation failures.

Mount API exceptions

mountFlowDropApp() throws synchronously if the mount cannot proceed.

Error message	Cause	Fix
`Container element not found`	The selector or element passed to `container` does not exist in the DOM	Ensure the container element exists before calling `mountFlowDropApp()`
`Container has no dimensions`	The container element has zero width or height	Apply `width` and `height` (or `min-height`) to the container via CSS before mounting
`FlowDrop CSS not imported`	The base styles from `@flowdrop/flowdrop/styles` were not loaded	Import `@flowdrop/flowdrop/styles` before mounting
`Cannot mount in server-side context`	`mountFlowDropApp()` was called during SSR (no `window` object)	Guard the call with `if (typeof window !== 'undefined')` — see Framework Integration

// Safe mount pattern
if (typeof window !== 'undefined') {
  const app = await mountFlowDropApp(document.getElementById('editor'), {
    // ...options
  });
}

API error handling

FlowDrop calls your REST API during normal operation. Use the onApiError event handler to intercept these errors.

const app = await mountFlowDropApp(document.getElementById('editor'), {
  endpointConfig: createEndpointConfig('/api/flowdrop'),
  eventHandlers: {
    onApiError: (error, operation) => {
      // error.message — error description
      // operation     — what FlowDrop was doing when the error occurred

      if (error.status === 401) {
        // Redirect to login
        window.location.href = '/login';
        return true; // return true to suppress the default toast notification
      }

      // Return false (or nothing) to show the default error toast
      return false;
    }
  }
});

HTTP status codes

Status	Cause	Recommended action
`0`	Network error — no response received	Check server is running; show connectivity warning
`401`	Unauthorized — missing or expired credentials	Redirect to login or refresh token
`403`	Forbidden — authenticated but not allowed	Show permission error; do not redirect
`404`	Endpoint not found — wrong URL configured	Verify your endpoint configuration
`422`	Validation error — malformed workflow JSON	Log the response body for details
`500`	Server error	Log and surface to user; offer retry

`operation` values

The operation argument tells you what FlowDrop was doing when the error occurred:

Value	Trigger
`loadNodes`	Initial `GET /nodes` request on mount
`loadWorkflow`	`GET /workflows/:id` on mount
`saveWorkflow`	`POST /workflows` or `PUT /workflows/:id` on save
`loadPortConfig`	`GET /port-config` for dynamic port compatibility
`executeWorkflow`	`POST /execute` (if using the playground)

Save errors

onSaveError is a separate handler called when a save operation fails. It receives the workflow object that failed to save, allowing you to recover or retry.

const app = await mountFlowDropApp(document.getElementById('editor'), {
  eventHandlers: {
    onSaveError: async (error, workflow) => {
      console.error('Save failed:', error);
      // workflow is the workflow object that failed to persist
      // You can store it locally or retry:
      localStorage.setItem('flowdrop-save-fallback', JSON.stringify(workflow));
    }
  }
});

Agent Spec validation errors

When exporting a workflow to Agent Spec format via WorkflowOperationsHelper.exportAsAgentSpec(), the result object indicates success or failure:

const result = WorkflowOperationsHelper.exportAsAgentSpec(workflow);
// result: { valid: boolean, errors: string[], warnings: string[] }

if (!result.valid) {
  console.error('Export failed:', result.errors);
}

Common validation errors

Error message	Cause	Fix
`Workflow has no nodes`	The workflow is empty	Add at least one node before exporting
`Cycle detected`	The workflow graph contains a loop	Remove cyclic connections; Agent Spec requires a DAG
`Node type not mappable: <type>`	A custom node type has no Agent Spec equivalent	Map custom types to Agent Spec actions in your export config
`Disconnected node: <id>`	A node has no edges	Connect all nodes or remove unused ones
`Missing required port: <port>`	A required input port has no incoming edge	Connect the required port before exporting

Warnings (non-fatal) indicate information that may be lost in the export, such as FlowDrop-specific configuration fields that have no Agent Spec equivalent.