Troubleshooting a Run

Collect evidence first

A missing target or model reference is different from a worker failure. Record the Run generation, phase, message, conditions, and namespace before changing configuration. Redact prompts, credentials, and customer data from any shared logs.

kubectl get agent,team,modelendpoint,run -n kaigents
kubectl describe run first-run -n kaigents
kubectl get run first-run -n kaigents -o yaml
kubectl get pods -n kaigents

No work starts

• Check that the Agent or Team exists in the same namespace and that the chart installed the expected CRDs.
• Inspect the operator pod health, RBAC errors, and image pull status.
• Verify the configured adapter URL and that Temporal is reachable.

Model calls fail

• Check ModelEndpoint.spec.url or serviceDns and verify network resolution from the runner.
• Confirm the model name actually exists on the server and is OpenAI-compatible for chat.
• Check authentication without printing API keys in logs or terminal output.
• Separate context-window and timeout failures from model-server unavailability.

A tool fails or hangs

• Compare Tool and MCPServer references with the Agent tool names and allowedTools.
• Inspect the correlated tool failure event and server-side logs.
• Check whether the server answers contract discovery and whether the call exceeds configured timeout or output size.
• Do not replay a tool with external side effects until you understand whether its previous attempt succeeded.

Waiting for approval

A gated Work Request can remain in WaitingForApproval until a valid approval or rework signal arrives. Confirm the workflow identity, the current step, and the required reviewer before sending a signal. Rework is bounded to avoid an unending loop.

Report a reproducible bug

Include the Kaigents release, chart version, redacted resource manifest, expected and observed status, and relevant component logs. Do not include production artifacts or credentials in public issues.