Troubleshooting Kubernetes Worker Run Failures with HTML Error Messages

Last updated: September 9, 2025

If you're experiencing Kubernetes worker run failures with cryptic HTML error messages containing encoded content or HTML snippets, this typically indicates that the worker cannot properly access your Git repository or is being intercepted by a proxy or firewall.

Understanding the Error

When you see error messages containing HTML content like <img> tags, base64-encoded data, or references to logos and stylesheets, this usually means:

  • The worker is receiving an HTML error page instead of the expected Git repository content

  • A reverse proxy (like Cloudflare) or firewall is blocking or redirecting the request

  • The worker cannot download required binaries (such as OpenTofu/Terraform)

Viewing Detailed Logs

To get more detailed information about what's causing the failure:

  1. Navigate to your failed run in the Spacelift UI

  2. Toggle off the simplified view using the blue toggle on the right side

  3. Review the logs from the preparing phase to identify the specific component that failed to download or access

Troubleshooting Steps

Check Repository Access

Test repository access from within your Kubernetes cluster:

curl -v <your-repo-url-or-archive-endpoint>

If you receive HTML content instead of a .tar.gz archive or proper API response, the worker cannot reach the correct content.

Verify Network Configuration

Ensure your worker has proper network access:

  • Outbound internet access is allowed for downloading archives and binaries

  • DNS resolution is working correctly

  • If using a private SCM, verify network routes are configured properly

  • Check that worker IPs are whitelisted in any firewalls or proxies

Validate Git Integration

In your Spacelift dashboard:

  1. Go to Integrations > Git Repositories

  2. Verify that tokens or app credentials are still valid

  3. Re-authenticate or reconnect the repository if needed

Handling Transient Failures

Since these errors can be intermittent (affecting only a small percentage of runs), consider implementing a retry policy to automatically handle such transient network or download failures.

Getting Additional Help

If you continue experiencing issues, follow the diagnostic steps in our Kubernetes Workers troubleshooting guide and provide the output to our support team for further analysis.