> ## Documentation Index
> Fetch the complete documentation index at: https://docs.trycordage.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Connecting Nodes

> Master data flow between nodes in your workflows

Connections (also called edges) define how data flows between nodes. Understanding connections is essential for building effective workflows.

## Creating Connections

### Basic Connection

1. Hover over the **output handle** (right side) of a source node
2. Click and drag to create a connection line
3. Drop onto the **input handle** (left side) of a target node
4. Release to complete the connection

<Tip>
  You can also drag from an input handle to an output handle - the direction doesn't matter when creating.
</Tip>

### Connection Validation

Cordage validates connections to prevent errors:

* **Type compatibility**: Image outputs connect to image inputs, text to text, etc.
* **Cycle detection**: Connections that would create loops are prevented
* **Handle availability**: Each input can only have one incoming connection

If a connection is invalid, you'll see an error message explaining why.

## Understanding Data Flow

### Execution Order

Workflows execute in **topological order**:

1. Nodes with no inputs (entry nodes) execute first
2. Downstream nodes execute after their inputs are ready
3. Multiple branches can execute in parallel

```mermaid theme={null}
flowchart LR
    A[Text Input] --> C[Model]
    B[Image Input] --> C
    C --> D[Export]
```

In this example:

1. Text Input and Image Input execute (or are ready) first
2. Model executes once both inputs are available
3. Export executes after Model completes

### Data Types

Common data types in Cordage:

| Type     | Description    | Example Nodes                   |
| -------- | -------------- | ------------------------------- |
| `text`   | String data    | Text Input, LLM Text            |
| `image`  | Image URL/data | Image Input, Model outputs      |
| `video`  | Video URL/data | Video Input, Video models       |
| `audio`  | Audio URL/data | Audio Input                     |
| `number` | Numeric values | Parameters, sliders             |
| `array`  | Lists of items | Iterator outputs, multi-outputs |

### Type Coercion

Some connections allow automatic type conversion:

* Numbers can convert to text
* Single items can convert to arrays
* URLs can represent images/videos

## Managing Connections

### Viewing Connection Details

* Hover over a connection line to see data type
* Selected connections are highlighted
* Data flows from left (output) to right (input)

### Removing Connections

* Click a connection line to select it
* Press **Delete** or **Backspace**
* Or right-click the connection and select **Delete**

### Rerouting Connections

To change where a connection goes:

1. Delete the existing connection
2. Create a new connection to the desired target

## Multiple Inputs and Outputs

### Multiple Outputs

Some nodes have multiple output handles:

```mermaid theme={null}
flowchart LR
    subgraph Model["Model Node"]
        O1["output (primary image)"]
        O2["metadata (generation info)"]
        O3["seed (random seed used)"]
    end
```

Connect each output to different downstream nodes as needed.

### Multiple Inputs

Model nodes often have many inputs:

```mermaid theme={null}
flowchart RL
    subgraph Model["Model"]
        I1["prompt"]
        I2["negative_prompt"]
        I3["image (for img2img)"]
        I4["width"]
        I5["height"]
        I6["seed"]
    end
```

Not all inputs are required - check the node documentation.

### Fan-Out Pattern

One output can connect to multiple inputs:

```mermaid theme={null}
flowchart LR
    A[Image Input] --> B[Crop Tool]
    A --> C[Blur Tool]
    A --> D[Resize Tool]
```

All three tools receive the same image.

### Fan-In Pattern

Multiple outputs can't connect to the same input. Instead, use combination nodes:

```mermaid theme={null}
flowchart LR
    A[Text A] --> C[Prompt Concatenator]
    B[Text B] --> C
    C --> D[Model]
```

## Special Connection Patterns

### Conditional Branching

Use Array Selector to choose between outputs:

```mermaid theme={null}
flowchart LR
    A[Model A] --> C[Array Node]
    B[Model B] --> C
    C --> D[Selector]
    D --> E[Export]
```

### Feedback Loops

Direct loops aren't allowed, but you can:

1. Run a workflow to completion
2. Use the output as input for a new run
3. Use iterators for multiple passes

### Optional Connections

Some inputs are optional:

* Image-to-image models work with or without an input image
* Negative prompts can be empty
* Default values are used for unconnected optional inputs

## Connection Best Practices

<Tip>
  **Keep connections organized** - Avoid crossing lines when possible. Use node positioning to create clean flows.
</Tip>

<Tip>
  **Use intermediate nodes** - If a connection path is complex, add utility nodes to clarify the flow.
</Tip>

<Tip>
  **Label connection purposes** - Use Comment nodes to explain non-obvious connections.
</Tip>

<Tip>
  **Test partial flows** - Verify connections work before building the full pipeline.
</Tip>

## Troubleshooting

### "Cannot create connection"

* Check type compatibility between output and input
* Ensure the connection wouldn't create a cycle
* Verify the input doesn't already have a connection

### "Connection has no data"

* Ensure the source node has executed
* Check that the source node completed successfully
* Verify the output handle has data (some are conditional)

### "Cycle detected"

The connection would create a loop. Restructure your workflow:

* Use iterators for repeated processing
* Split into separate workflows
* Use export/import for manual feedback