AI Model Troubleshooting
Diagnose connection, qualification, parser, and model-selection failures in an on-prem deployment.
Check problems in this order:
- Confirm the base URL, scheme, hostname, port, and
/v1path where required. - Confirm the inference server is reachable from the PacketSafari containers, not only from the deployment host.
- Approve the host when it is outside the PacketSafari container network.
- Install the private CA when internal HTTPS uses a private or self-signed certificate.
- Confirm corporate proxy settings when the customer network requires them.
- Run
Test connection, thenRefresh models. - Confirm the exact served model ID and model profile.
- Confirm the inference server uses the parser required by its installed release.
- Run
Qualify selected model; do not treat discovery as Agent readiness.
| Symptom | Likely cause | Action |
|---|---|---|
| Pending approval banner | Endpoint host is not allowlisted | Run the displayed approve-ai-host command on the deployment host. |
| Connection refused or timeout | Wrong URL, endpoint down, proxy block, or missing approval | Verify endpoint reachability, URL, proxy logs, and approval state. |
| Certificate verification failure | Private CA is not trusted by egress-ironproxy | Install the CA and restart the proxy. |
| Model is absent after connection succeeds | Discovery is unavailable or the served ID differs | Refresh models or enter the exact model ID manually. |
| Qualification fails on tool calls | Wrong tool parser or incompatible server/model revision | Check the installed vLLM/SGLang parser matrix and update the model profile. |
| Qualification passes but investigation quality is poor | Protocol compatibility does not guarantee model quality | Keep the route out of production and test a representative PCAP or another qualified model. |
For egress diagnostics, PacketSafari also includes:
python3 scripts/test_egress_enforcement.py
python3 scripts/test_external_ai_host_approval.py