AGI
AGI script returning -1 in Asterisk
When AGI returns -1, the dialplan did its job and the script did not. That is useful, because it means the answer is in the script's own logging, not anywhere in the Asterisk configuration.
What it looks like in the log
[2026-08-17 13:12:48] WARNING[10022][C-000015c8] res_agi.c: /var/lib/asterisk/agi-bin/lookup.py: returning -1What it means
AGI runs an external program and speaks a simple protocol with it over stdin and stdout. A return of -1 means that program exited without completing the conversation normally - it crashed, exited early, or deliberately signalled failure.
Asterisk has no visibility into why. From its side, the process ended and the channel was handed back. Everything about the cause lives in the script's environment, which is why the fix always starts by looking outside Asterisk.
Most common causes
-
01An unhandled exception in the script
A lookup that returned nothing, a network call that timed out, a field that was not where the script expected it. The script raises, exits non-zero, and Asterisk reports -1.
-
02The file is not executable
A script copied without its permission bits cannot run at all. The failure is immediate and identical to a crash.
-
03A missing or wrong interpreter
A shebang pointing at
/usr/bin/pythonon a box that only has/usr/bin/python3fails before the first line of the script executes. -
04A dependency not installed for the right user
Asterisk runs as its own user. A library installed under root's home, or a virtualenv the asterisk user cannot read, is not available at runtime even though it works when you test by hand.
-
05Output that breaks the AGI protocol
Anything the script prints to stdout that is not a valid AGI command corrupts the conversation. A stray debug print is enough.
How to tell which one it is
Run the script by hand as the asterisk user rather than as yourself. That single step catches permissions, interpreter and dependency problems, which together account for most of these, and it catches them in seconds.
Then check the script's own log around the timestamp in the Asterisk warning. If it has no logging of its own, that is the first thing to add - a script that can fail silently will fail silently again.
How to fix it
-
Test as the asterisk user
Use
sudo -u asteriskto run the script directly. If it fails there and works for you, the difference is environment, not logic. -
Fix permissions and the shebang
Confirm the executable bit is set and the interpreter path in the shebang actually exists on this box.
-
Send debug output to stderr, never stdout
Asterisk captures stderr into its log and leaves stdout for the protocol. Debug prints belong on stderr.
-
Handle failure inside the script
Catching exceptions and returning cleanly lets the dialplan branch on a result instead of aborting, which turns a broken call into a handled one.