Troubleshooting

The Action Says legId is required

Cause:

• the action could not resolve a leg ID from explicit options or the current item

Check:

1. does the incoming item contain json.legId or json.sipPbx.legId?
2. did a previous node accidentally remove json.sipPbx?
3. should you set Options -> Leg ID explicitly?

Typical places this happens:

• after using generic transform nodes that overwrite json
• when branching away from the original trigger item

The Action Says dialIds are required

Cause:

• a dial control action or wait action cannot find the dial session ID

Check:

• json.dialId
• json.sipPbx.dialId
• explicit Options -> Dial IDs for Wait Event
• explicit Options -> Dial ID for Break

The Action Says recordRequestId, authRequestId, or aiToolRequestId Is Required

Cause:

• a Respond action lost the original response handle and no explicit request ID was provided

Fix:

• keep the original trigger item intact
• or set Options -> Request ID
• or restore the value from json.sipPbx

Wait For Event Times Out Immediately

Expected if:

• timeoutSeconds = 0

Unexpected if:

• the timeout is too low for the real caller behavior
• the wrong leg or dial ID is being watched

Wait Media -> Timeout Has No mediaId

This can be expected.

The timeout path is not guaranteed to carry a fully resolved media payload. Build timeout logic around the branch itself and eventType = "timeout", not around mediaId or legId.

Extension Dial Finds No Targets

Possible reasons:

• the extension is not registered
• the endpoint exists in a different workflow scope
• Only Free Endpoints is enabled and all matching endpoints are busy
• you mistyped the extension number list

What to remember:

• extension dialing searches same-workflow extensions refs
• it does not search unrelated workflows

Queue Dispatch Never Happens

Check all of the following:

1. the caller was actually enqueued
2. the queue trigger is active
3. the queue trigger has operator extension numbers configured
4. matching extension endpoints are registered
5. those endpoints are available if you rely on free-only behavior

Also inspect whether the queue is repeatedly reaching Offline because retries are exhausted.

Hold Music Starts but Never Stops

This usually means you used background playback intentionally but never followed it with:

• Stop Media
• or Wait Media

Recommended pattern:

• save the returned mediaId
• stop it explicitly when the queue dispatch or bridge event happens
• or let a later call.wait stop looping on call_queue_removed if queue owns that caller lifecycle

Record Audio or Respond to recording Produces No File

Check:

1. is the file path valid on the n8n host?
2. does the n8n process have write permission?
3. are you waiting for completion when you expect final file metadata?
4. if using HTTP upload, are auth and headers correct?

HTTP Media Works Without Auth in Tests but Fails in Production

Possible reasons:

• wrong credential type selected
• upstream requires a different auth method
• your custom headers conflict with provider auth headers

Remember:

• the node resolves auth into a normalized URL and header set before calling the runtime

AI action allows at most one ai_memory connection

Cause:

• Attach Voice Agent received more than one ai_memory input

Fix:

• connect only one memory input

AI action ai_memory requires @langchain/core/messages

Cause:

• the connected memory object is not compatible with the native structured memory integration expected by the current implementation

Fix:

• use a LangChain-compatible memory integration that exposes the required message constructors and chatHistory.addMessages

The Voice Agent Cannot Call My Tool

Check:

1. was the tool connected as an ai_tool input to Attach Voice Agent?
2. does the tool expose a valid name and parameter schema?
3. did you use Invoke AI Tool for the tool node?
4. does the workflow respond through Respond To AI Tool?

Trigger Ref Collisions

If activation fails because a trigger already exists:

• you likely reused the same public ref where uniqueness is enforced

Best practice:

• keep refs globally unique unless you intentionally rely on advanced flow scoping rules

SIP Transport Expectations

Current public UI expectation:

• use UDP for SIP credentials and extensions transport selection

If you are trying to build a workflow around a transport not exposed in the node UI, treat that as unsupported for end-user documentation and normal production setup.

Linux Runtime Expectations

The published package ships Linux native prebuilds. If your host platform does not match the supported prebuild targets, installation or runtime startup can fail before any workflow logic starts.

When to Open an Issue

Open a GitHub issue when you can clearly provide:

• package version
• host OS and architecture
• whether you use trunk, extensions, queue, or WebSocket mode
• the exact node operation that failed
• whether the failure is configuration-time, activation-time, or during a live call