Troubleshooting

This guide aims to provide solutions to common issues encountered when using our services.

Workloads not retrievable from CI pipeline

If your workloads fail to appear when trying to add them to an environment, despite having connected your CI pipeline, ensure that you have followed these steps:

  1. Verify that you’ve incorporated the snippet into your pipeline configuration to transmit the image to Humanitec. Make sure the YAML is correctly formatted.
  2. Check if the Humanitec API token has been added as a variable for your repository.
  3. Have you initiated a new build after implementing the previous steps?

If these steps are followed and the problem persists, please contact our support team.

Deployment failure (using pre-configured Humanitec cluster)

Below are some typical reasons your environment might fail to deploy using the Humanitec-managed cluster.

Kubernetes connection error

A Kubernetes connection error can occur if Humanitec is unable to establish a connection to the Kubernetes API, or if the connection is successful, but Kubernetes fails to execute the deployment request.

  • Try redeploying by clicking the deployment button again.
  • If the error persists, please submit a help request.

Broken pod

During the creation of pods for your workloads by Kubernetes, a pod might fail due to a misconfiguration in the workload’s Dockerfile or its configurations.

Please ensure that your workload’s Dockerfile executes correctly. The logs can be viewed via the Humanitec interface by navigating to your Application, selecting the workload, and accessing its Logs section.

Unable to connect to an external resource

If your Application relies on an external resource such as an external database or API that Humanitec cannot connect to, the deployment will fail.

  • Enabling logging in your Application is advised. Logs can be viewed in the Humanitec interface by navigating to your Application, selecting the workload, and accessing its Logs section.

Inability to access Workload at configured DNS

Use the following to help debug issues with accessing a workload at its configured DNS.

Ingress configured

To access a workload via a DNS name, Ingress needs to be properly configured. Check if Ingress is set up by navigating to the Workload details page of the Active Deployment. If configured, the Ingress and DNS name should be visible below Resource dependencies in the left column.

If no Ingress cards are visible in the Ingress section, you should add one.

Request returning a 503 error

This error often results from incorrect Ingress configuration. Make sure the port Ingress is configured to on the workload matches the one being listened to by one of the services in a container within that workload.

If the request encounters a certificate error, this could be due to several reasons:

Serving “kubernetes ingress controller fake certificate”

This typically occurs when a conflict arises between the default ingress controller and a user-installed one. If you have set up your own ingress resource definition, ensure that the class field is accurately filled. Here’s an example of setting the class field for ingress-nginx:

curl https://api.humanitec.io/orgs/${HUMANITEC_ORG}/resources/defs/${DEFINITION_ID} \
  -X PATCH \
  -H "Authorization: Bearer ${HUMANITEC_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
  "driver_inputs": {
    "values": {
      "class": "nginx"
    }
  }
}'

Replace HUMANITEC_TOKEN, HUMANITEC_ORG, and DEFINITION_ID with relevant values.

Unavailability of features in the UI

Certain features may not be visible in the Humanitec UI due to interference from ad blockers or other browser settings. This is because Humanitec employs a system called Optimizely for UI feature flags. To access all Humanitec features, you may need to manually whitelist calls to https://cdn.optimizely.com/ in your ad-blocking extension, or turn off the ad-blocking service.

Issues with Google login

Logging into Humanitec via the Google social authentication feature requires the setting of third-party cookies.

You can find more information on this at developers.google.com.

The Google login requires permission for third-party cookies to be set, which can be blocked by browser security settings or add-ons such as Privacy Badger.

Please allow third-party cookies to be set when using Google sign-in with Humanitec.

Deployment failed

If a deployment fails, you’ll see your deployment in the Failed status. To get more information and details, select View deployment details.

The detailed view shows you the error message and the logs of the deployment to help debug the issue.

FAQs

Health status