{"record":{"id":"6896ae76789e7f2f","repo":"alibaba/open-code-review","slug":"scan-failed-w","errorCode":null,"errorMessage":"scan failed: %w","messagePattern":"scan failed: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/opencodereview/scan_cmd.go","lineNumber":243,"sourceCode":"\tctx, span := telemetry.StartSpan(telemetry.ContextWithTraceParentFromEnv(context.Background()), \"scan.run\")\n\tdefer span.End()\n\tvar traceID string\n\tif telemetry.IsEnabled() {\n\t\ttraceID = telemetry.TraceIDFromContext(ctx)\n\t\tif !isMachineReadable(opts.outputFormat) {\n\t\t\tfmt.Fprintf(os.Stderr, \"[ocr] TraceID: %s\\n\", traceID)\n\t\t}\n\t}\n\tstartTime := time.Now()\n\n\tcomments, err := ag.Run(ctx)\n\tif err != nil {\n\t\tspan.SetStatus(codes.Error, err.Error())\n\t\tspan.RecordError(err)\n\t\tif id := ag.SessionID(); id != \"\" {\n\t\t\tfmt.Fprintf(os.Stderr, \"[ocr] Session: %s (retry with: --resume %s)\\n\", id, id)\n\t\t}\n\t\treturn fmt.Errorf(\"scan failed: %w\", err)\n\t}\n\n\treturn emitRunResult(ctx, ag, comments, startTime, opts.outputFormat, opts.audience, q, llmIdentity, out, nil)\n}\n\nfunc loadScanResumeState(repoDir string, opts scanOptions, scanPaths []string) (*session.ResumeState, error) {\n\tif opts.resume == \"\" {\n\t\treturn nil, nil\n\t}\n\tstate, err := session.LoadResumeState(repoDir, opts.resume)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"load resume session: %w (run 'ocr session list' to see available sessions)\", err)\n\t}\n\tif err := state.ValidateScanOptions(scanPaths); err != nil {\n\t\treturn nil, fmt.Errorf(\"%w (run 'ocr session list' to see available sessions)\", err)\n\t}\n\tif state.CompletedCount() == 0 {\n\t\treturn nil, fmt.Errorf(\"resume session %q has no completed scan items (run 'ocr session list' to see available sessions)\", opts.resume)","sourceCodeStart":225,"sourceCodeEnd":261,"githubUrl":"https://github.com/alibaba/open-code-review/blob/5cf97d0d15cbd41b602513c4be3bfec3cee5bf7f/cmd/opencodereview/scan_cmd.go#L225-L261","documentation":"The agent-driven scan run returned an error from ag.Run/RunManifest; executeScan records it on the OpenTelemetry span, prints the session id (for retry with --resume), and wraps it as \"scan failed: %w\". This is the top-level wrapper for any failure during the actual LLM/tool loop of a full-file scan (network, auth, provider errors, tool-loop limits, panics surfaced as errors).","triggerScenarios":"Any error escaping the scan agent's run loop: LLM API call failure (network, 401/429/500), context deadline per file, tool-request budget exhausted, or template/session errors raised mid-run.","commonSituations":"Invalid or missing API key for the configured provider; rate limiting during large scans; network outage or proxy blocking the provider endpoint; a single huge file blowing the token budget; transient provider 5xx.","solutions":["Read the wrapped cause: fix auth (check API key env var / config for the chosen --provider) or network first.","Re-run with --resume <session-id> — the CLI prints the session id so completed files are skipped.","Reduce scope with --path / --exclude, or lower concurrency and raise --per-file-timeout to avoid timeouts.","Retry later if the cause was 429/5xx rate limiting or a provider outage."],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// Pre-flight before starting a scan\nif os.Getenv(\"<PROVIDER>_API_KEY\") == \"\" && !providerKeyInConfig() {\n    return fmt.Errorf(\"no API key configured for provider %q\", provider)\n}\nif _, err := net.DialTimeout(\"tcp\", providerHost+\":443\", 3*time.Second); err != nil {\n    return fmt.Errorf(\"provider unreachable: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"err := executeScan(opts)\nif err != nil {\n    if isRetryable(err) { // 429/5xx/timeouts from the wrapped cause\n        backoffThenRetryWithResume(opts) // reuse printed --resume session id\n    } else {\n        log.Fatalf(\"scan failed: %v\", err)\n    }\n}","preventionTips":["Always capture the printed session id; use --resume to continue after failures.","Set explicit provider/model and verify the API key before long scans.","Use --path/--exclude to bound scan size and --per-file-timeout for huge files.","Handle 429 rate limits by lowering concurrency rather than hammering retries."],"tags":["go","cli","llm","scan","network"],"backgroundTag":"scan-run-failed","analyzedSha":"5cf97d0d15cbd41b602513c4be3bfec3cee5bf7f","analyzedAt":"2026-09-02T02:08:09.116Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-08T10:18:20.063Z"}