AI Model Troubleshooting · Documentation

Check problems in this order:

Confirm the base URL, scheme, hostname, port, and /v1 path 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.
Save the connection, use Models → Refresh models, then Health → Test model. The latter uses model credits and does not attempt fallback.
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.
Team cannot see an otherwise available model	Connection grants, model audience/workflows, or member model-selection permission	Check all three under AI Access; saving provider credentials alone is not a grant.
Model uses unexpected reasoning	Explicit run, environment, settings-file or saved CLI override	Inspect effective run settings and remove the override before testing the per-model default.
Requests fail only under parallel load	Inference-server queue, context or memory capacity	Reproduce at one active request, then increase gradually; size server admission limits and worker capacity from measurements.
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