Connection Rules

Understanding how nodes connect and data flows through your workflows.

Handle Types

Each node input and output has a type that determines what connections are valid.

Primary Types

Type	Color	Description
image	Blue	Static images (PNG, JPG, WebP, GIF)
video	Purple	Video files (MP4, WebM, MOV)
audio	Green	Audio files (MP3, WAV, OGG)
text	Yellow	Text strings, prompts
any	Gray	Universal type -- accepts any type

Additional Types

Type	Color	Description
flow	Primary	Flow control / trigger signals
mask	Amber	Image masks (compatible with image)
ctx	Yellow	Context data (compatible with text)
capture	Amber	Capture data (compatible with image and video)

Connection Compatibility

Basic Rules

1. Same types connect: Matching types always connect

[image] --> [image]   ok
[video] --> [video]   ok
[text]  --> [text]    ok

2. any accepts all: Gray handles accept any type

[image] --> [any]   ok
[video] --> [any]   ok
[text]  --> [any]   ok

3. any provides all: Gray outputs connect to any input

[any] --> [image]   ok
[any] --> [text]    ok
[any] --> [video]   ok

4. Different media types don't cross: Incompatible types reject connections

[text]  --> [image]   no
[audio] --> [video]   no
[image] --> [video]   no

Full Compatibility Matrix

This is the actual compatibility from nodeConnectionSchema.ts:

Source Type	Can Connect To
image	image, any
video	video, any
audio	audio, any
text	text, ctx, flow, any
flow	flow, text, any
ctx	ctx, text, any
mask	mask, image, any
any	image, video, audio, text, flow, any, mask, scene, capture, ctx
capture	capture, image, video, any

Key compatibility notes:

• text can connect to flow and ctx inputs (and vice versa) -- they are interchangeable for data passing
• mask can connect to image inputs -- masks are treated as a specialized image type
• capture can connect to both image and video inputs

Connection Behavior

Single vs Multiple Connections

Output handles can connect to multiple inputs:

[Text to Image output] --> [Preview input]
                       --> [Image Upscale input]
                       --> [Variant Generator input]

Input handles typically accept one connection:

[Text to Image prompt input] <-- [Text Prompt output]

Some inputs accept multiple connections (e.g., Sync Gate):

[Sync Gate input] <-- [Node A output]
                  <-- [Node B output]
                  <-- [Node C output]

Data Flow Direction

Data flows from left to right:

• Outputs are on the right side of nodes
• Inputs are on the left side of nodes

[Node A] --output--> input--[Node B]

Visual Indicators

Connection States

State	Appearance	Meaning
Valid	Solid line	Connection is valid
Active	Animated line	Data is flowing
Error	Red line	Connection problem
Batch	Dotted line (strokeDasharray: '5,5')	Within batch scope

Creating Connections

When dragging to create a connection:

1. Valid target - Handle highlights, cursor shows plus
2. Invalid target - Handle doesn't highlight, cursor shows no-entry
3. Drop on canvas - Shows compatible node suggestions

Edge Styling

Normal edge:     ------------------->
Active edge:     ===================> (animated)
Batch scope:     - - - - - - - - - -> (dotted)
Selected edge:   ===================> (thick)

Troubleshooting Connections

Cannot Connect

Symptoms: Handle won't accept connection

Causes:

1. Type mismatch -- check handle colors match or are compatible
2. Already connected -- some inputs only accept one connection
3. Circular dependency -- would create a loop in the DAG

Solutions:

1. Add a conversion node (Brain for text-to-structured, Analyzer for image-to-text)
2. Disconnect existing connection first
3. Restructure workflow to avoid cycles

Data Not Flowing

Symptoms: Connected but no data transfers

Causes:

1. Upstream node not executed yet
2. Upstream node produced an error
3. Execution hasn't reached that branch

Solutions:

1. Check upstream node status indicators
2. Fix any errors in the chain
3. Verify the workflow is running

Unexpected Data

Symptoms: Wrong data arrives at node

Causes:

1. Wrong connection source
2. Batch context confusion ($item vs direct input)

Solutions:

1. Verify connection endpoints
2. Add Inspect node to debug data structure
3. Check batch scope boundaries

Best Practices

1. Use Consistent Types

Match types throughout your workflow:

ok: [Text Prompt] --> [Text to Image] --> [Preview Media]
       (text)          (image out)         (image in)

no: [Text Prompt] --> [Preview Media]
       (text)          (expects image/video/audio)

2. Leverage any Handles

Use any for flexible connections:

[Multiple outputs] --> [Sync Gate (any)] --> [Brain (any)] --> [Specific output]

3. Add Preview/Inspect Nodes

Debug with intermediate nodes:

[Source] --> [Inspect] --> [Process] --> [Preview Media]
                |
          [see data structure]

4. Keep Connections Organized

• Avoid crossing edges when possible
• Use consistent left-to-right flow
• Group related nodes together

5. Document Complex Connections

Use PostIt nodes to explain:

[PostIt: "Data splits here for A/B testing"]
           |
[Node] --> [Branch A]
       --> [Branch B]