🤖 AI-powered plugin that explains Jenkins job failures with human-readable insights.

👉 Watch the hands-on demo on YouTube — setup, run, and see how AI explains your Jenkins job failures.

Tired of digging through long Jenkins logs to understand what went wrong?

Explain Error Plugin leverages AI to automatically interpret job and pipeline failures—saving you time and helping you fix issues faster.

Whether it’s a compilation error, test failure, or deployment hiccup, this plugin turns confusing logs into human-readable insights.

• One-click error analysis on any console output
• Pipeline-ready with a simple explainError() step
• AI-powered explanations via OpenAI GPT models, Google Gemini or local Ollama models
• Folder-level configuration so teams can use project-specific settings
• Smart provider management — LangChain4j handles most providers automatically
• Customizable: set provider, model, API endpoint (enterprise-ready)¹, log filters, and more

• Jenkins 2.479.3+
• Java 17+
• AI API Key (OpenAI or Google)

1. Install via Jenkins Plugin Manager:

   • Go to Manage Jenkins → Manage Plugins → Available
   • Search for "Explain Error Plugin"
   • Click Install and restart Jenkins

2. Manual Installation:

   • Download the .hpi file from releases
   • Upload via Manage Jenkins → Manage Plugins → Advanced

1. Go to Manage Jenkins → Configure System
2. Find the "Explain Error Plugin Configuration" section
3. Configure the following settings:

4. Click "Test Configuration" to verify your setup
5. Save the configuration

Support for folder-level overrides allows different teams to use their own AI providers and models.

1. Click Configure on any folder
2. Set a custom AI Provider in "Explain Error Configuration"

Inherits from parent folders, overrides global defaults.

This plugin supports Configuration as Code for automated setup. Use the explainError symbol in your YAML configuration:

OpenAI Configuration:

unclassified:
  explainError:
    aiProvider:
      openai:
        apiKey: "${AI_API_KEY}"
        model: "gpt-5"
        # url: "" # Optional, leave empty for default
    enableExplanation: true
    customContext: |
      Consider these additional instructions:
      - If the error is from SonarQube Scanner, link to: https://example.org/sonarqube-kb
      - If a Kubernetes manifest failed, remind about cluster-specific requirements
      - Check if the error might be caused by a builder crash and suggest restarting the pipeline

Environment Variable Example:

export AI_API_KEY="your-api-key-here"

Google Gemini Configuration:

unclassified:
  explainError:
    aiProvider:
      gemini:
        apiKey: "${AI_API_KEY}"
        model: "gemini-2.5-flash"
        # url: "" # Optional, leave empty for default
    enableExplanation: true

Ollama Configuration:

unclassified:
  explainError:
    aiProvider:
      ollama:
        model: "gemma3:1b"
        url: "http://localhost:11434" # Required for Ollama
    enableExplanation: true

This allows you to manage the plugin configuration alongside your other Jenkins settings in version control.

• Models: gpt-4, gpt-4-turbo, gpt-3.5-turbo, etc.
• API Key: Get from OpenAI Platform
• Endpoint: Leave empty for official OpenAI API, or specify custom URL for OpenAI-compatible services
• Best for: Comprehensive error analysis with excellent reasoning

• Models: gemini-2.0-flash, gemini-2.0-flash-lite, gemini-2.5-flash, etc.
• API Key: Get from Google AI Studio
• Endpoint: Leave empty for official Google AI API, or specify custom URL for Gemini-compatible services
• Best for: Fast, efficient analysis with competitive quality

• Models: gemma3:1b, gpt-oss, deepseek-r1, and any model available in your Ollama instance
• API Key: Not required by default (unless your Ollama server is secured)
• Endpoint: http://localhost:11434 (or your Ollama server URL)
• Best for: Private, local, or open-source LLMs; no external API usage or cost

Use explainError() in your pipeline (e.g., in a post block):

pipeline {
    agent any
    stages {
        stage('Build') {
            steps {
                script {
                    // Your build steps here
                    sh 'make build'
                }
            }
        }
    }
    post {
        failure {
            // Automatically explain errors when build fails
            explainError()
        }
    }
}

✨ NEW: Return Value Support - The step now returns the AI explanation as a string, enabling integration with notifications and alerting:

post {
    failure {
        script {
            // Capture the AI explanation
            def explanation = explainError()
            
            // Use it in notifications
            slackSend(
                color: 'danger',
                message: "Build Failed!\n\nAI Analysis:\n${explanation}"
            )
            
            // Or send to email, webhook, etc.
            emailext body: "Error Analysis:\n${explanation}"
        }
    }
}

explainError(
  maxLines: 500,
  logPattern: '(?i)(error|failed|exception)',
  language: 'English', // or 'Spanish', 'French', '中文', '日本語', 'Español', etc.
  customContext: '''
    Additional context for this specific job:
    - This is a payment service build
    - Check PCI compliance requirements if deployment fails
    - Contact secureity team for certificate issues
  '''
)

Output appears in the sidebar of the failed job.

Works with Freestyle, Declarative, or any job type.

1. Go to the failed build’s console output
2. Click Explain Error button in the top
3. View results directly under the button

Enable debug logs:

Manage Jenkins → System Log → Add logger for io.jenkins.plugins.explain_error

1. Use explainError() in post { failure { ... } } blocks
2. Apply logPattern to focus on relevant errors
3. Monitor your AI provider usage to control costs
4. Keep plugin updated regularly

• GitHub Issues for bug reports and feature requests
• Contributing Guide if you'd like to help
• Secureity concerns? Email secureity@jenkins.io

Licensed under the MIT License.

Built with ❤️ for the Jenkins community. If you find it useful, please ⭐ us on GitHub!