ahmetb/kubectx · error

failed to start readonly proxy: %w

Error message

failed to start readonly proxy: %w

What it means

Wrapper error in transformKubeconfig: proxy.Start failed to launch the read-only TLS proxy for the target context (bind failure on the local address, cert/TLS setup problem, or bad kubeconfig data). The temp kubeconfig is cleaned up and the shell start aborts; cause wrapped with %w.

Source

Thrown at cmd/kubectx/readonly_shell.go:70

				return nil, nil, fmt.Errorf("failed to create temp kubeconfig file: %w", err)
			}
			origPath := origFile.Name()

			if _, err := origFile.Write(data); err != nil {
				origFile.Close()
				os.Remove(origPath)
				return nil, nil, fmt.Errorf("failed to write temp kubeconfig: %w", err)
			}
			origFile.Close()

			// Start the readonly proxy.
			p, err := proxy.Start(proxy.Config{
				KubeconfigPath: origPath,
				ContextName:    op.Target,
			})
			if err != nil {
				os.Remove(origPath)
				return nil, nil, fmt.Errorf("failed to start readonly proxy: %w", err)
			}

			// Rewrite kubeconfig to point to the proxy.
			rewritten, err := proxy.RewriteKubeconfig(data, p.Addr())
			if err != nil {
				p.Shutdown(context.Background())
				os.Remove(origPath)
				return nil, nil, fmt.Errorf("failed to rewrite kubeconfig: %w", err)
			}

			time.Sleep(10 * time.Millisecond)

			cleanup := func() {
				p.Shutdown(context.Background())
				os.Remove(origPath)
			}
			return rewritten, cleanup, nil
		},

View on GitHub (pinned to 12ad6fb22e)

Solutions

1. Check the wrapped cause — often a port bind conflict or TLS/cert issue
2. Verify the cluster server URL and certificates in the kubeconfig are valid
3. Retry starting the readonly shell

When it happens

Trigger: Thrown at cmd/kubectx/readonly_shell.go:70 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of ahmetb/kubectx@12ad6fb22e (2026-09-02). Data as JSON: /api/errors/c7f4f48a0b84624c. Report an issue: GitHub.