> ## Documentation Index > Fetch the complete documentation index at: https://allhandsai-docs-litellm-proxy-screenshot.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Troubleshooting > Collect diagnostics and inspect OpenHands Enterprise (OHE) workloads. OpenHands Enterprise Replicated VM installations run in a Replicated Embedded Cluster which is a Kubernetes cluster based on k0s. Once you have access to the VM, you can use standard Kubernetes commands to inspect OHE. For Helm deployments, use your existing Kubernetes access to run the same commands. Most OHE workloads run in the `openhands` namespace. The Replicated Admin Console runs in `kotsadm`, and ingress runs in `traefik`. ## Start With a Support Bundle A support bundle is the fastest way to give OpenHands Support a snapshot of the installation. You do not need to investigate the problem yourself before opening a support ticket. ### Use the Admin Console For a Replicated VM installation: 1. Open `https://admin.:30000`. 2. Select `Troubleshoot`. 3. Select `Analyze` and wait for it to finish. 4. Select `Download bundle`. If `Send bundle to vendor` is available, you can upload the bundle for us to inspect directly. Sending a support bundle does not automatically create a support ticket, so be sure to still open a support ticket and mention the support bundle upload. ### Use the Command Line On a Replicated VM, use the command line when the Admin Console is unavailable. For a Helm installation, run the Kubernetes command from a workstation with `kubectl` access. Connect to the VM and run: ```bash theme={null} sudo /var/lib/embedded-cluster/bin/openhands support-bundle ``` If the installation did not complete, run the original installer from the directory where you extracted it: ```bash theme={null} sudo ./openhands support-bundle ``` For OHE installed with Helm in an existing Kubernetes cluster, run this command from a workstation with `kubectl` access: ```bash theme={null} kubectl support-bundle --load-cluster-specs --namespace openhands ``` See the [Kubernetes installation guide](/enterprise/k8s-install/installation#step-5-validate-the-installation) if the `support-bundle` CLI is not installed. The bundle includes cluster health, Kubernetes resource state, application logs, and OHE service checks. A support bundle may contain sensitive cluster configuration or logs. Keep it local while you inspect it, and review it before attaching it to a ticket or uploading it. A healthy analyzer summary does not prove that a user can open the conversation UI and complete a conversation. ### Open a Support Ticket Open the OpenHands Support Portal provided during Enterprise onboarding. Please attach the generated archive. If you used `Send bundle to vendor`, mention the upload in the ticket. Include: * When the problem occurred, including the time zone. * The affected user or conversation ID, when applicable. * The expected and actual behavior. * Any recent upgrade or configuration change. * Steps that reproduce the problem. If you cannot access the Support Portal, please contact your OpenHands representative for more assistance. ## Inspect the Deployment This workflow is for practitioners who are already familiar with `kubectl`. Keep your investigation read-only. Do not change Kubernetes resources unless directed by OpenHands Support. Ad hoc `kubectl` changes can be overwritten during a deployment or upgrade and may leave the installation in an inconsistent state. ### Get a Kubernetes Session Connect to a controller VM. On a single-node installation, this is the OHE VM. Then run: ```bash theme={null} sudo /var/lib/embedded-cluster/bin/openhands shell ``` This opens a shell with `kubectl` configured for the embedded cluster. Run `exit` when finished. Use your existing Kubernetes access and confirm the current context: ```bash theme={null} kubectl config current-context kubectl get pods -n openhands ``` ### Check Overall Status Record the time, then inspect the cluster and recent events: ```bash theme={null} date -u kubectl get nodes -o wide kubectl get pods -n openhands -o wide kubectl get deployments,statefulsets -n openhands kubectl get events -n openhands --sort-by=.metadata.creationTimestamp ``` For Helm installations that use the separate sandbox namespace from the [installation guide](/enterprise/k8s-install/installation), also check it: ```bash theme={null} kubectl get pods -n openhands-runtimes -o wide kubectl get events -n openhands-runtimes --sort-by=.metadata.creationTimestamp ``` Start with the `STATUS`, `READY`, and `RESTARTS` columns: * `Pending` usually points to scheduling, storage, or capacity problems. * `Init:` means an init container has not completed. Check that container's logs. * `CrashLoopBackOff` means a container repeatedly exits. Check previous logs. * A pod that is not ready or keeps restarting usually has a failed dependency, health check, or resource limit. If the Kubernetes Metrics API is available, check current resource usage: ```bash theme={null} kubectl top pods -n openhands ``` ### Inspect a Pod and Its Logs ```bash theme={null} kubectl describe pod -n openhands kubectl logs -n openhands \ --all-containers=true --since=30m --timestamps kubectl logs -n openhands \ --all-containers=true --previous --timestamps kubectl logs -n openhands -c \ --since=10m --timestamps --follow ``` Use `--previous` after a container restarts. Use `-c` to select a specific container, including an init container such as `migrate-db`. On a Replicated VM, these logs are also written to files on the VM. See [Log Collection](/enterprise/vm-install/log-collection) to send them to your own observability platform. ### Choose the Right Component Pod names may include a release prefix and generated suffix. Match the recognizable component name to the table below. | Component | Investigate when | | - | - | | `openhands` | Web application, API, conversations, and general application errors. | | `openhands-integrations` | Integration events and background integration work. | | `runtime-api` | Sandbox creation, startup, pause, and cleanup. | | `runtime-...` | A particular conversation's sandbox. | | `litellm` | Model-provider requests and authentication. | | `keycloak` | Login, SSO, and authentication. | | `kotsadm` namespace | Replicated Admin Console problems. | ### Temporarily Enable Debug Logging On a Replicated VM, `Log Level` defaults to `INFO`. Use `DEBUG` only during a short investigation: 1. In the Admin Console, select `Config`. 2. Under `Troubleshooting`, set `Log Level` to `DEBUG`. 3. Save and deploy, then reproduce the problem. 4. Collect the logs or a support bundle. 5. Return `Log Level` to `INFO`, then save and deploy again. ## First-Conversation Checks Use these checks after login if the conversation UI does not open or the first conversation cannot run. Start with the error visible to the user. Keep the investigation read-only; apply corrections through Helm values or the documented Secret creation path after you identify the cause. | Symptom | Check | | - | - | | Login succeeds but the conversation UI fails or asks for a backend URL or API key | Check the frontend Deployment, Service, and Ingress for your chart version. On chart `0.71.1`, a redirect to `/canvas` requires the [version-specific Canvas values](/enterprise/k8s-install/installation#step-3-configure-values). A healthy application pod alone does not prove the frontend is ready. | | Conversation says “Failed to start sandbox” | Inspect `runtime-api` logs and the sandbox namespace. If Runtime API `GET /list` returns 401, verify that `default-api-key` and `sandbox-api-key` contain the same value. Do not print either value. | | First model request fails with an invalid proxy token, wrong model, or OpenAI endpoint | Check the user's selected LLM profile, `env.LITELLM_DEFAULT_MODEL`, the bundled LiteLLM model list, and the profile's base URL. On chart `0.71.1`, the first user's `Default` profile can differ from the configured model. | For a Helm install, inspect the application resources and sandbox state with: ```bash theme={null} kubectl get deployment,service,ingress -n openhands kubectl get pods,events -n openhands-runtimes ``` If the Runtime API logs show a 401, compare the two Secret fields without displaying their values or hashes: ```bash theme={null} if [ "$(kubectl -n openhands get secret default-api-key \ -o jsonpath='{.data.default-api-key}')" = \ "$(kubectl -n openhands get secret sandbox-api-key \ -o jsonpath='{.data.sandbox-api-key}')" ]; then echo "Runtime API keys match" else echo "Runtime API keys differ" fi ``` Do not run this comparison with shell tracing (`set -x`) enabled. If you correct either Secret, the application pod must restart before its secret-backed environment reloads. Use your deployment's normal rollout procedure, then retry a new conversation. If the profile points at the wrong model endpoint, inspect the selected profile before changing infrastructure credentials or entering an API key in the browser. ## Related Guides Install an OpenHands Enterprise VM deployment. Configure a Replicated VM installation. Install OHE into an existing Kubernetes cluster. Diagnose and tune CPU, memory, replicas, and storage. Send VM installation logs to your own observability platform. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.