Debug Pipeline

Debug Pipeline

Diagnose pipeline executions and suggest fixes via MCP.

Instructions

Step 1: Diagnose Execution (Preferred)

Use the dedicated diagnosis tool. It accepts an executionid, pipelineid (auto-fetches latest execution), or a Harness URL:

Call MCP tool: harness_diagnose
Parameters:
  pipeline_id: ""   # or execution_id or url
  org_id: ""
  project_id: ""

This returns a structured report with stage/step breakdown, timing, bottlenecks, and failure details in one call. It also automatically follows chained (child) pipeline failures.

Step 1b: Full Diagnostic Mode

For deeper analysis, request logs and pipeline YAML:

Call MCP tool: harness_diagnose
Parameters:
  execution_id: ""
  org_id: ""
  project_id: ""
  summary: false               # raw diagnostic payload
  include_yaml: true           # include pipeline definition
  include_logs: true           # include failed step logs
  log_snippet_lines: 120       # tail N lines per step (0 = unlimited)
  max_failed_steps: 5          # cap number of steps to fetch logs for

Diagnose Parameters

| Parameter | Default | Description | |-----------|---------|-------------| | execution_id | -- | Specific execution to analyze | | pipeline_id | -- | Fetch latest execution for this pipeline | | url | -- | Harness UI URL (auto-extracts IDs) | | summary | true | Structured report (true) or raw payload (false) | | include_yaml | false (summary) / true (raw) | Include pipeline YAML definition | | include_logs | false (summary) / true (raw) | Include failed step logs | | log_snippet_lines | 120 | Max log lines per step (tail). 0 = unlimited | | max_failed_steps | 5 | Max steps to fetch logs for. 0 = unlimited |

Step 2: Project Health Overview

Check overall project health for context:

Call MCP tool: harness_status
Parameters:
  org_id: ""
  project_id: ""

Shows recent failed executions, running executions, and deployment activity.

Step 3: Find Failed Executions (if needed)

Call MCP tool: harness_list
Parameters:
  resource_type: "execution"
  org_id: ""
  project_id: ""
  search_term: ""

Step 4: Get Execution Details

Call MCP tool: harness_get
Parameters:
  resource_type: "execution"
  resource_id: ""
  org_id: ""
  project_id: ""

Step 5: Get Execution Logs

Call MCP tool: harness_get
Parameters:
  resource_type: "execution_log"
  resource_id: ""
  org_id: ""
  project_id: ""

Step 6: Get Pipeline Definition

Call MCP tool: harness_get
Parameters:
  resource_type: "pipeline"
  resource_id: ""
  org_id: ""
  project_id: ""

Analysis Framework

Categorize errors and provide targeted fixes:

Build Failures

• Missing dependencies - Check package.json/requirements.txt
• Compilation errors - Review recent code changes
• Docker build failures - Check Dockerfile and base image

Infrastructure Errors

• "No delegate available" - Check delegate status, verify tags match
• Connector failures - Rotate credentials, test connection
• Resource limits - Check cloud quotas and limits

Configuration Errors

• "Secret not found" - Verify secret exists at correct scope (account/org/project)
• "Could not resolve expression" - Check expression syntax
• "Connector not found" - Verify connectorRef identifier

Deployment Errors

• ImagePullBackOff - Check registry credentials and image tag
• CrashLoopBackOff - Check container logs, resource limits
• Readiness probe failed - Review probe configuration

Timeout Errors

• Step/stage exceeded timeout - Increase timeout or optimize
• Delegate task queued too long - Scale up delegates

Artifact Errors

• "Artifact not found" - Verify artifact path, check upstream build

Response Format

## Pipeline Failure Analysis

**Pipeline:** 
**Execution:** 
**Failed At:** 

### Failure Summary
**Stage:** 
**Step:** 
**Error:** 

### Root Cause

### Fix
**Immediate:** 
**Prevention:** 

Examples

• "Why did my build pipeline fail?" - Use harness_diagnose with pipeline_id
• "Debug execution abc123" - Use harness_diagnose with execution_id
• "Show me recent failures" - Use harness_status then drill into failures
• "Analyze the pipeline at https://app.harness.io/..." - Pass URL directly to harness_diagnose
• "Which stage is the bottleneck in my pipeline?" - Use harness_diagnose on a successful execution
• "Get full logs for the failed deploy step" - Use harness_diagnose with include_logs: true

Performance Notes

• Take your time analyzing logs thoroughly. Read complete error messages and stack traces before diagnosing.
• Check all failed steps, not just the first one. Multiple failures may share a root cause or reveal a dependency chain.
• Quality of diagnosis is more important than speed. A wrong diagnosis wastes more time than a thorough one.

Troubleshooting

Logs Not Available

• Logs expire based on retention settings
• Very recent executions may have delayed logs
• Aborted executions may not have complete logs

Cannot Find Execution

• Verify org/project scope
• Remove filters to see all executions
• Check RBAC permissions

MCP Connection Issues

• Verify MCP server is running and connected
• Check API key validity
• Ensure required toolsets (pipelines, logs) are enabled

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: harness
• Source: harness/harness-skills
• License: Apache-2.0
• Homepage: https://developer.harness.io/docs/platform/harness-ai/harness-skills/

Install and usage instructions live in the source repository linked above.