Chatqna Troubleshoot

<!--
SPDX-FileCopyrightText: (C) 2026 Intel Corporation
SPDX-License-Identifier: Apache-2.0
-->

ChatQnA Troubleshooting

Systematic troubleshooting for Chat Question-and-Answer Core issues using repo-documented commands and runtime-aware checks.

Codebase root: sample-applications/chat-question-and-answer-core/

Environment setup (run first)

This skill drives Chat Question-and-Answer Core through its real source files, so the ChatQnA application must be present and commands must run from the app root. Do this before any troubleshooting steps, whether or not the source is already in your workspace.

Run the bundled bootstrap. It first tries to find an existing ChatQnA checkout by walking up from the current directory and checking the enclosing git repo, then reuses it without re-cloning. Only when no checkout is found does it do a shallow, single-branch, sparse checkout of just sample-applications/chat-question-and-answer-core from main.

It prints the resolved app root on stdout:

# SKILL_DIR is this skill directory. In-repo it is:
# .github/skills/chatqna-troubleshoot
SKILL_DIR=".github/skills/chatqna-troubleshoot"
APP_ROOT="$(bash "$SKILL_DIR/scripts/chatqna-bootstrap.sh")"
cd "$APP_ROOT"

Every command below assumes the working directory is this APP_ROOT.

To use a fork/branch or a specific clone path, override these before running the bootstrap script:

• CHATQNA_REPO_URL
• CHATQNA_REPO_BRANCH
• CHATQNA_CLONE_DIR
• CHATQNA_FORCE_CLONE (set to 1 to force clone)

What This Skill Produces

• A symptom-to-root-cause troubleshooting path tailored to deployment mode:
  • Docker Compose deployment
  • Helm/Kubernetes deployment
  • Local build and unit test workflow
• Command evidence for each hypothesis tested (status, logs, endpoint output).
• A concise diagnosis summary:
  • observed symptom
  • validated root cause
  • exact corrective action
  • verification command confirming fix

When to Use

• "ChatQnA is not working"
• "health endpoint fails"
• "chat returns 500"
• "containers keep restarting"
• "helm pod is crashlooping"
• "docs/openapi page is unavailable"
• "documents upload fails"
• "OpenVINO/Ollama runtime mismatch issues"

Inputs To Confirm

Collect or infer these first:

1. Deployment type: docker-compose or helm
2. Runtime: openvino or ollama
3. Device mode for OpenVINO: cpu or gpu
4. Host/namespace context:
   • Docker: HOST_IP (default 127.0.0.1)
   • Helm: namespace and release name
5. User-visible symptom and first failure point:
   • startup
   • UI reachability
   • API endpoint behavior
   • model/runtime errors
   • ingestion/chat failures

If any value is missing, infer from active services/logs and state assumptions explicitly.

Diagnostic Decision Tree

1. If deployment does not start or pods/containers are not healthy:
   • run startup diagnostics first.
2. If deployment starts but UI/docs are unreachable:
   • run gateway/network diagnostics.
3. If health is up but /chat or /documents fails:
   • run API/runtime diagnostics.
4. If failures mention model loading, private model, or device:
   • run model/config diagnostics.
5. For Helm issues, include PVC and namespace checks.

Troubleshooting Workflow

Run from sample-applications/chat-question-and-answer-core unless noted.

1. Baseline Environment Checks

Validate required tools and environment:

docker --version

For Docker deployment paths:

docker compose version

For Helm deployment paths:

helm version
kubectl version --client

If commands are missing, stop and report install prerequisites from docs.

2. Startup Diagnostics

Docker Compose

Ensure correct runtime profile export was done in the current shell:

# OpenVINO CPU
source scripts/setup_env.sh

# OpenVINO GPU
# source scripts/setup_env.sh -d gpu

# Ollama CPU
# source scripts/setup_env.sh -b ollama

Start and inspect:

docker compose -f docker/compose.yaml up -d
docker compose -f docker/compose.yaml ps
docker compose -f docker/compose.yaml logs --tail=200

If GPU requested, verify render nodes:

ls -l /dev/dri/render*

If GPU nodes are absent, recommend CPU fallback and re-run with CPU profile.

Helm/Kubernetes

Check workload state:

kubectl get pods -n <namespace>
kubectl get svc -n <namespace>
kubectl describe pod <pod-name> -n <namespace>
kubectl logs <pod-name> -n <namespace>

If PVC or scheduling blocks startup, inspect PVC and node constraints:

kubectl get pvc -n <namespace>

If stale PVC blocks recovery, delete only the affected PVC after user confirmation:

kubectl delete pvc <pvc-name> -n <namespace>

3. Gateway and Reachability Diagnostics

For Helm/Kubernetes, always pair kubectl describe pod with kubectl logs for the nginx/UI pod before probing endpoints, even if kubectl get pods already showed Running:

kubectl describe pod <nginx-or-ui-pod-name> -n <namespace>
kubectl logs <nginx-or-ui-pod-name> -n <namespace>

Probe gateway endpoints through nginx exposure on port 8102:

HOST_IP=${HOST_IP:-127.0.0.1}
BASE_URL="http://${HOST_IP}:8102/v1/chatqna"

curl -sS -w "\nHTTP_STATUS:%{http_code}\n" "${BASE_URL}/health"
curl -sS -w "\nHTTP_STATUS:%{http_code}\n" "http://${HOST_IP}:8102/v1/chatqna/docs"
curl -sS -w "\nHTTP_STATUS:%{http_code}\n" "http://${HOST_IP}:8102/v1/chatqna/openapi.json"

If docs/openapi fail but containers are up, check nginx container logs and service exposure.