feat: add documentation URL for database lock errors (#9531)

Author: knqyf263

cmd/trivy/main.go

@@ -47,6 +47,5 @@ func run() error {
 	// Set up signal handling for graceful shutdown
 	ctx := commands.NotifyContext(context.Background())
 
-	app := commands.NewApp()
-	return app.ExecuteContext(ctx)
+	return commands.Run(ctx)
 }

pkg/cache/fs.go

@@ -9,6 +9,7 @@ import (
 
 	"github.com/hashicorp/go-multierror"
 	bolt "go.etcd.io/bbolt"
+	bberrors "go.etcd.io/bbolt/errors"
 	"golang.org/x/xerrors"
 
 	"github.com/aquasecurity/trivy/pkg/fanal/types"
@@ -34,7 +35,7 @@ func NewFSCache(cacheDir string) (FSCache, error) {
 	})
 	if err != nil {
 		// Check if the error is due to timeout (database locked by another process)
-		if errors.Is(err, bolt.ErrTimeout) {
+		if errors.Is(err, bberrors.ErrTimeout) {
 			return FSCache{}, xerrors.Errorf("cache may be in use by another process: %w", err)
 		}
 		return FSCache{}, xerrors.Errorf("unable to open cache DB: %w", err)

pkg/commands/artifact/run.go

@@ -367,13 +367,6 @@ func Run(ctx context.Context, opts flag.Options, targetKind TargetKind) (err err
 	ctx, cancel := context.WithTimeout(ctx, opts.Timeout)
 	defer cancel()
 
-	defer func() {
-		if errors.Is(err, context.DeadlineExceeded) {
-			// e.g. https://trivy.dev/latest/docs/configuration/
-			log.WarnContext(ctx, fmt.Sprintf("Provide a higher timeout value, see %s", doc.URL("/docs/configuration/", "")))
-		}
-	}()
-
 	if opts.GenerateDefaultConfig {
 		log.Info("Writing the default config to trivy-default.yaml...")
 

pkg/commands/run.go

@@ -0,0 +1,33 @@
+package commands
+
+import (
+	"context"
+	"errors"
+	"fmt"
+
+	bberrors "go.etcd.io/bbolt/errors"
+
+	"github.com/aquasecurity/trivy/pkg/log"
+	"github.com/aquasecurity/trivy/pkg/version/doc"
+)
+
+const (
+	troubleshootingDocPath = "/docs/references/troubleshooting/"
+	lockDocFragment        = "database-and-cache-lock-errors"
+	timeoutDocFragment     = "timeout"
+)
+
+// Run builds the CLI application and executes it with centralized error handling.
+func Run(ctx context.Context) error {
+	app := NewApp()
+	if err := app.ExecuteContext(ctx); err != nil {
+		if errors.Is(err, context.DeadlineExceeded) {
+			log.WarnContext(ctx, fmt.Sprintf("Provide a higher timeout value, see %s", doc.URL(troubleshootingDocPath, timeoutDocFragment)))
+		}
+		if errors.Is(err, bberrors.ErrTimeout) {
+			log.ErrorContext(ctx, fmt.Sprintf("Failed to acquire cache or database lock, see %s for troubleshooting", doc.URL(troubleshootingDocPath, lockDocFragment)))
+		}
+		return err
+	}
+	return nil
+}

pkg/k8s/commands/run.go

@@ -3,7 +3,6 @@ package commands
 import (
 	"context"
 	"errors"
-	"fmt"
 
 	"github.com/spf13/viper"
 	"golang.org/x/xerrors"
@@ -19,7 +18,6 @@ import (
 	"github.com/aquasecurity/trivy/pkg/k8s/scanner"
 	"github.com/aquasecurity/trivy/pkg/log"
 	"github.com/aquasecurity/trivy/pkg/types"
-	"github.com/aquasecurity/trivy/pkg/version/doc"
 )
 
 // Run runs a k8s scan
@@ -37,14 +35,7 @@ func Run(ctx context.Context, args []string, opts flag.Options) error {
 		return xerrors.Errorf("failed getting k8s cluster: %w", err)
 	}
 	ctx, cancel := context.WithTimeout(ctx, opts.Timeout)
-
-	defer func() {
-		cancel()
-		if errors.Is(err, context.DeadlineExceeded) {
-			// e.g. https://trivy.dev/latest/docs/configuration
-			log.WarnContext(ctx, fmt.Sprintf("Provide a higher timeout value, see %s", doc.URL("/docs/configuration/", "")))
-		}
-	}()
+	defer cancel()
 	opts.K8sVersion = cluster.GetClusterVersion()
 	return clusterRun(ctx, opts, cluster)
 }