Gateway Exit Codes

Restart-intent exit codes that let systemd, Kubernetes, and s6 distinguish a recoverable blip from a fatal misconfiguration

praisonai serve gateway exits with a specific code to tell your supervisor whether to restart or stop — a misconfigured gateway should not crash-loop forever.

from praisonaiagents import Agent

agent = Agent(name="assistant", instructions="Serve users via the gateway.")
agent.start("Start the gateway under systemd supervision.")

The user runs the gateway under a supervisor; exit codes signal whether to restart, stop for config fixes, or exit cleanly.

Quick Start

1. Start the gateway normally

   praisonai gateway start --agents my_agents.yaml

   The process exits with code 0 on clean shutdown, 75 on transient failure (supervisor should restart), and 78 on fatal config error (supervisor should alert, not restart).

2. Systemd service with correct restart policy

   [Unit]
   Description=PraisonAI Gateway
   After=network.target
   
   [Service]
   ExecStart=/usr/local/bin/praisonai gateway start --agents /etc/praisonai/agents.yaml
   Restart=on-failure
   RestartSec=5
   # Restart on transient failure (75), but not on fatal config error (78)
   RestartForceExitStatus=75
   SuccessExitStatus=0
   
   [Install]
   WantedBy=multi-user.target

3. Kubernetes restart policy

   apiVersion: v1
   kind: Pod
   spec:
     restartPolicy: OnFailure
     containers:
       - name: praisonai-gateway
         image: praisonai/gateway:latest
         command: ["praisonai", "gateway", "start", "--agents", "/etc/praisonai/agents.yaml"]
         lifecycle:
           postStart:
             exec:
               command: ["/bin/sh", "-c", "echo Gateway started"]

   For exit code 78, set an alert in your monitoring system and do not auto-restart.

Exit Code Reference

Exit codes 75 (EX_TEMPFAIL) and 78 (EX_CONFIG) follow the BSD sysexits.h standard, which most Linux supervisors understand natively.

• Exit 75 is also emitted by LoopWatchdog when a wedged event loop is detected.
• Startup-phase wedge (PR #5266 / issue #5265): exit 75 is also emitted by StartupWatchdog when the startup deadline expires before confirm_loop_live(). The stack-dump header reads “gateway startup did not confirm a live event loop within ~Ns” — distinct from both the loop-wedge and shutdown-phase headers. Armed via Python arm(deadline_s=…) in a custom entry point (no CLI/YAML knob yet). See Startup Watchdog.
• Shutdown-phase deadline (PR #5084 / issue #5079): the LoopWatchdog shutdown-phase deadline fires os._exit(75) if graceful drain does not complete within drain_timeout + gateway.watchdog.shutdown_grace. The stack-dump header reads “graceful shutdown did not complete within ~Ns” instead of the loop-wedge header. Configured via gateway.watchdog.shutdown_grace (YAML) or stop(grace=…) (Python). See Loop Watchdog → Shutdown-phase deadline mode.

What Triggers Each Code

Fatal configuration (exit 78)

The gateway exits 78 when it detects a problem that restarting won’t fix:

• Missing required dependencies (e.g. platform SDK not installed)
• Missing or unreadable gateway.yaml
• Schema-invalid gateway.yaml (type errors, unknown keys)
• Unknown / typo’d channel platform — e.g. telegran: when you meant telegram:. Previously warned and started; now fails closed with exit 78.
• Missing token: on a tokenful platform — the token: key must be present; an empty ${VAR} resolution is tolerated (the channel is skipped), but a missing key is fatal.
• Plugin platform not on the registry — a platform: name that isn’t built-in, isn’t published via praisonai.channels / praisonai.bots entry points, and isn’t registered at runtime via register_platform() fails closed. To validate against your custom platform, register it before calling WebSocketGateway.start_with_config().
• --agents file with non-mapping entries
• Unresolved tool in the config (strict tool pre-flight) — a tool named in gateway.yaml that cannot be resolved (typo, uninstalled optional package, or a gated local tools.py). Strict is the default; pass --no-strict-tools or set strict_tools: false to warn-and-continue instead. See Pre-flight tool check.
• FatalConfigError raised by a plugin or adapter during startup

Transient failures (exit 75)

Everything else — network errors, upstream timeouts, unexpected exceptions during operation — exits 75.

Common Patterns

Raise FatalConfigError from a custom plugin

from praisonaiagents.gateway.protocols import FatalConfigError

class MyPlugin:
    def startup(self, config):
        if not config.get("api_key"):
            raise FatalConfigError("MyPlugin: 'api_key' is required in gateway.yaml")

Detect exit code in a shell script

#!/bin/bash
praisonai serve gateway --config gateway.yaml
CODE=$?

if [ "$CODE" -eq 78 ]; then
    echo "Fatal config error — alert on-call team" >&2
    send_alert "gateway misconfigured" &
    exit 1
elif [ "$CODE" -eq 75 ]; then
    echo "Transient failure — will restart" >&2
fi

Classify exits programmatically

from praisonaiagents.gateway import classify_exit_reason, FatalConfigError

try:
    run_gateway()
except Exception as exc:
    code = classify_exit_reason(exc)
    raise SystemExit(code)

Supervisor Configuration Reference

systemd

[Unit]
Description=PraisonAI Gateway
After=network.target

[Service]
ExecStart=/usr/local/bin/praisonai serve gateway
Restart=on-failure
RestartSec=2
# A typo in gateway.yaml exits 78 — don't crash-loop, page instead
RestartPreventExitStatus=78
SuccessExitStatus=0

[Install]
WantedBy=multi-user.target

Reload and enable:

systemctl daemon-reload
systemctl enable --now praisonai-gateway

How It Works

The classifier (classify_exit_reason) is a pure function with no side effects. It lives in the core package so the wrapper CLI (praisonai serve gateway) and the runtime entry point (python -m praisonai.runtime) share one source of truth.

Exit Code Reference

from praisonaiagents.gateway import (
    GATEWAY_OK_EXIT_CODE,         # 0
    GATEWAY_RESTART_EXIT_CODE,    # 75
    GATEWAY_FATAL_CONFIG_EXIT_CODE,  # 78
)

Fatal vs Transient

classify_exit_reason(exc) applies these rules in order:

Clean exit (0):

• exc is None
• exc is KeyboardInterrupt (includes SIGTERM mapped to KeyboardInterrupt)
• exc is SystemExit(0) or SystemExit(None)
• exc is SystemExit(n) where n is any integer — passes n through unchanged

Fatal (78 — do not restart):

• FatalConfigError raised explicitly anywhere in the start path
• gateway.yaml missing, empty, or schema-invalid (load_gateway_config raises ValueError)
• --agents file missing or unreadable
• agents: key absent or falsy in the agents YAML
• agents: is not a list (e.g. agents: {name: bad})
• agents: list contains a non-mapping entry (e.g. agents: ["bad"]) — previously triggered AttributeError and crash-looped at code 75; now correctly raises FatalConfigError and exits 78
• Unknown or typo’d channel platform (e.g. telegran:) — previously warned and started; now raises ValueError from the registry-aware validator and exits 78
• Missing token: key on a tokenful platform — previously warned; now fatal (an empty ${VAR} resolution is tolerated and the channel is skipped)
• Plugin platform: not on the registry (not built-in, not an entry point, not register_platform()d) — exits 78
• Unresolved tool named in the config under the strict tool pre-flight (default --strict-tools) — raise typer.Exit(78); opt out with --no-strict-tools or strict_tools: false
• Missing required gateway dependencies at boot (e.g. pip install praisonai[api] not run)

Transient (75 — ask supervisor to restart):

• Any Exception not matched by the rules above

Supervisor Integration

Installed daemons honour these exit codes automatically

praisonai-bot gateway install (and praisonai onboard) generate a unit that already stops on exit 78, so a broken gateway.yaml never crash-loops. Add RestartPreventExitStatus=78 yourself only when you hand-write the unit.

[Unit]
Description=PraisonAI Bot Service
After=network.target
StartLimitIntervalSec=60
StartLimitBurst=5

[Service]
Type=notify
NotifyAccess=main
WatchdogSec=30
Restart=on-failure
RestartSec=5
SuccessExitStatus=0
RestartPreventExitStatus=78

<key>KeepAlive</key>
<dict>
    <key>SuccessfulExit</key><false/>
    <key>Crashed</key><true/>
</dict>
<key>ThrottleInterval</key>
<integer>30</integer>

if "%ERRORLEVEL%"=="78" (
    echo PraisonAI gateway stopped: fatal config error 78. Fix the config and re-start.
    exit /b 0
)

Hand-written units

[Unit]
Description=PraisonAI Gateway
After=network.target

[Service]
ExecStart=/usr/local/bin/praisonai serve gateway
Restart=on-failure
RestartSec=2
# Exit 78 = fatal config; don't crash-loop, page the operator instead
RestartPreventExitStatus=78
SuccessExitStatus=0
# Optional: capture logs
StandardOutput=journal
StandardError=journal
SyslogIdentifier=praisonai-gateway

[Install]
WantedBy=multi-user.target

[Service]
ExecStart=/usr/local/bin/praisonai serve gateway --config /etc/praisonai/gateway.yaml
Restart=on-failure
RestartSec=2
RestartPreventExitStatus=78

apiVersion: v1
kind: Pod
spec:
  restartPolicy: OnFailure
  initContainers:
    - name: validate-config
      image: your-praisonai-image
      command: ["sh", "-c"]
      args:
        - |
          praisonai serve gateway --config /config/gateway.yaml --check-only
          if [ $? -eq 78 ]; then
            echo "FATAL: gateway.yaml is invalid — fix before deploying"
            exit 1
          fi
      volumeMounts:
        - name: gateway-config
          mountPath: /config
  containers:
    - name: gateway
      image: your-praisonai-image
      command: ["praisonai", "serve", "gateway", "--config", "/config/gateway.yaml"]
      volumeMounts:
        - name: gateway-config
          mountPath: /config
  volumes:
    - name: gateway-config
      configMap:
        name: gateway-config

#!/bin/sh
# finish — called by s6/runit after 'run' exits
# $1 = exit code from run

if [ "$1" = "78" ]; then
    # Fatal config — operator must fix gateway.yaml
    # Tell s6 to stop this service permanently (don't auto-restart)
    s6-svc -O .
fi

# For any other code (including 75), exit 0 to let the supervisor restart
exit 0

#!/bin/sh
# $1 = exit code, $2 = signal
if [ "$1" = "78" ]; then
    # Signal the runsvdir to down this service
    sv down .
fi

Embedding the Classifier

Use classify_exit_reason directly when you run the gateway start path from your own code:

import sys
from praisonaiagents.gateway import classify_exit_reason, FatalConfigError

def run_my_gateway():
    # ... your gateway startup logic ...
    pass

try:
    run_my_gateway()
except Exception as exc:
    sys.exit(classify_exit_reason(exc))

Signal “stop restarting me” from anywhere in a custom start path by raising FatalConfigError:

from praisonaiagents.gateway import FatalConfigError

def validate_my_config(path):
    if not config_is_valid(path):
        raise FatalConfigError(f"Invalid config at {path} — fix before restarting")

Backward Compatibility

The wrapper (praisonai serve gateway) imports the exit-code symbols from praisonaiagents.gateway at startup. Two fallback rules apply:

• If praisonaiagents.gateway is absent (ModuleNotFoundError) or predates the protocol (missing symbols → AttributeError), the wrapper uses local sysexits.h values (0 / 75 / 78) and a minimal classifier with the same semantics.
• Any other ImportError (a broken core install) surfaces immediately — broken cores are no longer silently swallowed.

Pre-PR #2439 wrappers returned None from start(); the new int return is backward-compatible — callers that ignored the return value continue to work and see exit 0 semantics from the shell.

s6-overlay

#!/bin/execlineb -P
# /etc/s6-overlay/s6-rc.d/gateway/run
foreground { praisonai serve gateway --config /etc/praisonai/gateway.yaml }
importas -u ? ?
ifelse { test ${?} -eq 78 } { s6-svscanctl -t /var/run/s6/services }

Docker Compose

services:
  gateway:
    image: praisonai/gateway:latest
    command: serve gateway --config /config/gateway.yaml
    restart: on-failure
    volumes:
      - ./gateway.yaml:/config/gateway.yaml

[Service]
ExecStart=praisonai gateway start --agents /etc/praisonai/agents.yaml
Restart=on-failure
RestartSec=5
RestartForceExitStatus=75
SuccessExitStatus=0 75

RestartForceExitStatus=75 tells systemd to restart even when Restart=on-failure would not normally trigger (e.g. the process exits quickly). Exit code 78 is NOT in RestartForceExitStatus, so systemd will not restart on fatal config errors.

Kubernetes

spec:
  restartPolicy: OnFailure
  containers:
    - name: gateway
      image: praisonai/gateway:latest
      command: ["praisonai", "gateway", "start"]
      env:
        - name: PRAISONAI_AGENTS_FILE
          value: /config/agents.yaml

Add a liveness probe alert on exit code 78:

livenessProbe:
  exec:
    command: ["test", "-f", "/tmp/gateway.ready"]
  initialDelaySeconds: 10
  periodSeconds: 30

s6 / runit

#!/bin/sh
# /etc/services.d/praisonai-gateway/run
exec praisonai gateway start --agents /etc/praisonai/agents.yaml

# /etc/services.d/praisonai-gateway/finish
#!/bin/sh
# $1 = exit code
if [ "$1" -eq 78 ]; then
  echo "Fatal config error — alerting operator"
  touch /tmp/praisonai-config-error
  exit 125  # s6: do not restart
fi

Best Practices

RestartPreventExitStatus=78

# Example: alert on 78 from journald
journalctl -u praisonai-gateway -f | grep "Fatal config"

# In your CI pipeline, before deploying:
praisonai serve gateway --config gateway.yaml
# Exit 78 will fail the pipeline step

# Wrong — crash-loops forever on a bad config
try:
    run_my_gateway()
except FatalConfigError:
    pass  # Don't do this

# Right — let the supervisor see 78
try:
    run_my_gateway()
except FatalConfigError as exc:
    sys.exit(78)

RestartSec=5
StartLimitIntervalSec=60
StartLimitBurst=5

Related