Refactor: Improve tracing error handling for OpenTelemetry

Co-authored-by: jacob <jacob@depot.dev>

Author: cursoragent

pkg/buildx/commands/bake.go

@@ -49,7 +49,7 @@ func RunBake(dockerCli command.Cli, in BakeOptions, validator BakeValidator, pri
 
 	ctx, end, err := tracing.TraceCurrentCommand(ctx, "bake")
 	if err != nil {
-		return nil, nil, err
+		return nil, nil, wrapTracingError(err)
 	}
 	defer func() {
 		end(err)

pkg/buildx/commands/build.go

@@ -140,7 +140,7 @@ func runBuild(dockerCli command.Cli, validatedOpts map[string]build.Options, in
 
 	ctx, end, err := tracing.TraceCurrentCommand(ctx, "build")
 	if err != nil {
-		return err
+		return wrapTracingError(err)
 	}
 	defer func() {
 		end(err)
@@ -1100,6 +1100,18 @@ func wrapBuildError(err error, bake bool) error {
 	return err
 }
 
+func wrapTracingError(err error) error {
+	if err == nil {
+		return nil
+	}
+	errMsg := err.Error()
+	if strings.Contains(errMsg, "conflicting Schema URL") || strings.Contains(errMsg, "cannot merge resource") {
+		msg := fmt.Sprintf("%s\n\nThis error is usually caused by conflicting OpenTelemetry environment variables.\nTo resolve this issue, try setting DEPOT_DISABLE_OTEL=1 in your environment.", errMsg)
+		return &wrapped{err, msg}
+	}
+	return err
+}
+
 type wrapped struct {
 	err error
 	msg string

pkg/buildx/commands/build_test.go

@@ -0,0 +1,75 @@
+package commands
+
+import (
+	"errors"
+	"strings"
+	"testing"
+)
+
+func TestWrapTracingError(t *testing.T) {
+	tests := []struct {
+		name          string
+		err           error
+		shouldWrap    bool
+		expectedMsg   string
+		expectedInMsg string
+	}{
+		{
+			name:       "nil error",
+			err:        nil,
+			shouldWrap: false,
+		},
+		{
+			name:          "conflicting Schema URL error",
+			err:           errors.New("Error: cannot merge resource due to conflicting Schema URL"),
+			shouldWrap:    true,
+			expectedInMsg: "DEPOT_DISABLE_OTEL=1",
+		},
+		{
+			name:          "cannot merge resource error",
+			err:           errors.New("cannot merge resource with different schema"),
+			shouldWrap:    true,
+			expectedInMsg: "OpenTelemetry environment variables",
+		},
+		{
+			name:       "unrelated error",
+			err:        errors.New("some other error"),
+			shouldWrap: false,
+		},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			result := wrapTracingError(tt.err)
+
+			if tt.err == nil {
+				if result != nil {
+					t.Errorf("expected nil error, got %v", result)
+				}
+				return
+			}
+
+			if tt.shouldWrap {
+				wrapped, ok := result.(*wrapped)
+				if !ok {
+					t.Errorf("expected wrapped error, got %T", result)
+					return
+				}
+
+				if !strings.Contains(wrapped.Error(), tt.expectedInMsg) {
+					t.Errorf("expected error message to contain %q, got %q", tt.expectedInMsg, wrapped.Error())
+				}
+
+				// Verify we can unwrap to get the original error
+				if errors.Unwrap(result) != tt.err {
+					t.Errorf("expected unwrapped error to be original error")
+				}
+			} else {
+				// Should return the original error unchanged
+				if result != tt.err {
+					t.Errorf("expected error to be unchanged, got %v", result)
+				}
+			}
+		})
+	}
+}