Error codes and troubleshooting

This page covers common errors encountered during development and deployment on the Newo platform, along with their causes and resolutions.

REST API error responses

The Newo REST APIs return errors in a standard JSON format:

{
  "code": 400,
  "type": "validation_error",
  "reason": "Invalid request body",
  "errors": [
    {
      "field": "connector_idn",
      "message": "connector_idn is required"
    }
  ]
}

HTTP status codes

Skill script errors

Action returns null unexpectedly

Symptom: A {% set %} variable is null when you expect a value.

Common causes:

• The attribute identifier is misspelled or does not exist for the account
• The persona has not yet had the attribute set
• The action was called outside the correct flow context (e.g., GetUser() in a timer skill where no user session is active)

Resolution: Log the return value with {{SendMessage(text=Stringify(value))}} in the Sandbox to inspect the actual output. Verify the attribute identifier using the Attribute Reference pages.

SendCommand() fires but no response event arrives

Symptom: A magic_http_response, magic_browser_response, or timer event never arrives after calling SendCommand().

Common causes:

• The connectorIdn in SendCommand() does not match the connector_idn in the event subscription
• The integration is not properly configured (missing API keys, invalid connector settings)
• The skill that calls SendCommand() exits before the response arrives (response events are asynchronous)

Resolution:

1. Check that connectorIdn in the SendCommand() call exactly matches connector_idn in the flow's event subscription.
2. Confirm the connector is properly configured in the Builder Integrations page.
3. Ensure the skill that calls SendCommand() does not block or return before the async response arrives — use a separate skill subscribed to the response event.

Gen() / GenStream() produces unexpected output

Symptom: The LLM generates an incorrect, off-topic, or incomplete response.

Diagnostic approach: See Debugging agent execution in the Advanced Topics section. The core principle: if the output is wrong, something was missing from or incorrect in the prompt.

1. Find the broken reply in Sandbox logs.
2. Open the prompt sent to the LLM (visible in session logs).
3. Identify which information block was missing or incorrect.

Variables from inside {% if %} or {% for %} are undefined outside the block

Symptom: A variable set inside a conditional block returns undefined when accessed later.

Resolution: In NSL, block scoping works differently from standard Jinja2 — variables set inside blocks are accessible outside. However, if a variable is only set in one branch of an {% if %}, it will be undefined if the other branch executes. Initialize variables with a default before the conditional:

{% set result = "" %}
{% if condition %}
  {% set result = "some value" %}
{% endif %}
{{ result }}

Voice channel errors

Calls drop immediately after answering

Common causes:

• STT provider is not configured or credentials are invalid
• The agent has no active flow or the conversation_started event has no subscription
• The Newo Voice connector is not properly provisioned

Resolution: Verify connector configuration in Builder. Check that the flow has an event subscription for conversation_started or user_message on the voice integration.

Call transfer fails silently

Common causes:

• The transfer_call_tool is configured but the escalation_phone customer attribute is empty
• The destination number is formatted incorrectly (must include country code)

Resolution: Confirm project_attributes_escalation_phone is set for the account. Ensure the number is in E.164 format (+15551234567).

Timer errors

Timer fires but handler skill doesn't execute

Common causes:

• The connectorIdn used in set_timer does not match any event subscription's connector_idn
• The flow containing the timer subscription is not the active flow for the persona

Resolution: Cross-check the connectorIdn value in the SendCommand() call against the connector_idn in the event subscription in the flow YAML.

Webhook errors

Outgoing webhook returns 400 from the target server

Common causes:

• Payload format does not match what the target server expects
• Missing or invalid authentication headers

Resolution: Inspect the webhook payload using the session logs. Confirm the target server's expected content type and authorization mechanism.

Incoming webhook payload is not processed

Common causes:

• The incoming webhook URL is not registered or is misconfigured
• The command_idn in the payload does not match a registered command

Resolution: Verify the webhook is registered via the Webhooks API. Check that the payload's command_idn matches a command registered in your flow.

Getting help

If you cannot resolve an issue using this guide:

1. Review Builder session logs — they contain full prompt content, event traces, and skill execution history.
2. Contact [email protected] with your customer IDN, a description of the issue, and relevant session log excerpts.