Troubleshooting

Troubleshooting

Common issues and solutions when integrating agents with SignalWire.

Connection Issues

Problem: Call doesn’t connect to agent

Check:

• Is the server running?
• Is the URL correct in SignalWire?
• Is HTTPS configured properly?
• Is the firewall allowing connections?
• Can you access the URL from browser?

Test:

$
curl -X POST https://your-server.com/ -H "Content-Type: application/json"

Authentication Errors

Problem: 401 Unauthorized

Check:

• Is basic auth enabled on the server?
• Are credentials in the URL correct?
• Are credentials URL-encoded if special chars?

URL Format:

https://username:password@your-server.com/

Special characters in password need encoding:

SWML Errors

Problem: Invalid SWML response

Verify with swaig-test:

$
swaig-test my_agent.py --dump-swml --raw

Common issues:

• Missing "version": "1.0.0"
• Invalid JSON format
• Missing required sections
• Syntax errors in SWML verbs

No Speech Response

Problem: Agent doesn’t speak

Check:

• Is a language configured? self.add_language("English", "en-US", "rime.spore")
• Is there a prompt? self.prompt_add_section("Role", "You are...")
• Is the AI model specified? Check SWML output for ai.params

Function Not Called

Problem: AI doesn’t call your function

Check:

• Is the function registered? Run swaig-test my_agent.py --list-tools
• Is the description clear? AI needs to understand when to use it
• Is the prompt mentioning the capability? Example: “You can check the weather using get_weather”

Function Errors

Problem: Function returns error

Test locally:

$
swaig-test my_agent.py --exec function_name --param value

Check:

• Are all required parameters provided?
• Is the handler returning SwaigFunctionResult?
• Are there exceptions in the handler?

Add error handling:

1
try:
2
    result = do_something()
3
    return SwaigFunctionResult(result)
4
except Exception as e:
5
    self.log.error(f"Error: {e}")
6
    return SwaigFunctionResult("Sorry, an error occurred")

SSL Certificate Issues

Problem: SSL handshake failed

Check:

• Is certificate valid and not expired?
• Is the full certificate chain provided?
• Is the domain correct on the certificate?

Test:

$
openssl s_client -connect your-server.com:443

For development, use ngrok (handles SSL automatically).

Timeout Issues

Problem: Requests timing out

SWML Request Timeout:

• SignalWire waits ~5 seconds for SWML
• Make sure server responds quickly

Function Timeout:

• SWAIG functions should complete in less than 30 seconds
• Use async operations for slow tasks
• Consider background processing for long tasks

Quick Diagnostic Steps

Getting Help

If issues persist:

1. Check SignalWire documentation
2. Review call logs in dashboard
3. Enable debug logging in your agent
4. Contact SignalWire support

Common Error Messages

Logging for Debugging

Enable detailed logging:

1
import logging
2
import structlog
3
4
## Enable debug logging
5
logging.basicConfig(level=logging.DEBUG)
6
7
## The agent uses structlog
8
structlog.configure(
9
    wrapper_class=structlog.make_filtering_bound_logger(logging.DEBUG)
10
)