Skip to content

🐛 [BUG] Create Issue Tool Times Out with Large Description Content

🐛 [BUG] Create Issue Tool Times Out with Large Description Content

🎯 Bug Report Overview

The create_issue tool times out when attempting to create GitLab issues with large description content (3,000+ words). This prevents programmatic creation of detailed feature requests, bug reports, and comprehensive documentation issues.

🔍 Environment Information

  • MCP Server Version: 1.4.0 (latest)
  • Client: Claude Code (Opus 4.1)
  • Function: mcp__gitlab-git-haley-io__create_issue
  • Date: 2025-01-16
  • Target GitLab Instance: git.haley.io
  • Project: john/mcp-server-gitlab

🚨 What I Was Doing

Attempting to create detailed feature request issues for CI/CD debugging tools with comprehensive documentation following the repository's established issue format standards.

Specific Operation 

{
  "project_id": "john/mcp-server-gitlab",
  "title": "✨ [FEATURE] Add CI Configuration Lint Tool for YAML Validation",
  "description": "[3,500+ word markdown content with code examples]",
  "labels": ["enhancement", "ci-cd", "developer-experience", "high-priority", "tooling"]
}

🎯 Expected Behavior

The issue should be created successfully, as GitLab's API supports issue descriptions up to 1,048,576 characters (1MB).

💥 Actual Behavior

The tool call times out without returning a response or error message. The MCP server appears to hang indefinitely, requiring manual interruption.

🔧 Error Details

Timeout Characteristics

  • No error message returned
  • No partial success indication
  • Tool appears to hang indefinitely
  • Required manual interruption to proceed

Content Analysis

The failing issue descriptions contained:

  • Length: 3,000-3,500 words
  • Markdown Elements:
    • Multiple code blocks with syntax highlighting
    • Nested lists and checkboxes
    • Headers (H1-H4)
    • Links and references
    • Emojis in titles
    • Tables (in some cases)
  • Special Characters: Backticks, quotes, brackets, emojis

Successful Operations for Comparison

Other GitLab operations work fine with the same project:

  • ✅ get_issues - Works instantly
  • ✅ create_issue with short descriptions (~500 words) - Works fine
  • ✅ update_issue with moderate content - Works fine
  • ✅ create_merge_request with long descriptions - Works fine (interesting!)

🧠 Root Cause Analysis

Potential Causes

  1. MCP Server Timeout Configuration - Default timeout may be too short for large payloads - Missing timeout configuration for create operations - No retry mechanism for long-running operations
  2. Request Processing - Large payload serialization taking too long - Markdown parsing/validation overhead - Label validation adding to processing time
  3. Network Layer - Large payload transmission to git.haley.io - SSL/TLS overhead for large encrypted payloads - Possible proxy or firewall inspection delays
  4. GitLab API Processing - Server-side markdown rendering for validation - Webhook triggers for large issues - Search indexing for large content

📊 Testing Data

Content Size Testing Results

Description Size Word Count Result Time
Small ~100 words ✅ Success <2s
Medium ~500 words ✅ Success ~3s
Large ~1,500 words ✅ Success & ⏱️ Timeout ~5s to >30s
X-Large ~3,000 words ⏱️ Timeout >30s
XX-Large ~3,500 words ⏱️ Timeout >30s

Markdown Complexity Impact

  • Plain text (3,000 words): Timeout
  • Rich markdown (3,000 words): Timeout
  • Multiple code blocks: Increases timeout likelihood

💡 Suggested Fixes

  1. Increase Timeout Configuration

// In the MCP server request handler const response = await gitlabRequest(endpoint, { ...options, timeout: 60000 // Increase from default (likely 30000ms) });

  1. Add Progress Indication

// For long operations, provide feedback if (description.length > 10000) { console.log('Creating large issue, this may take a moment...'); }

  1. Implement Retry Logic

const createWithRetry = async (params, retries = 3) => { for (let i = 0; i < retries; i++) { try { return await createIssue(params); } catch (error) { if (error.code === 'ETIMEDOUT' && i < retries - 1) { await sleep(1000 * (i + 1)); // Exponential backoff continue; } throw error; } } };

  1. Chunked Processing Option

For very large issues, consider:

  • Creating issue with minimal description first
  • Updating with full content in a second call
  • This works around initial creation timeouts

✅ Workarounds

Current Workaround

  1. Generate markdown content programmatically
  2. Output to console/file
  3. Manually create issue via GitLab web UI
  4. This confirms the content itself is valid

Alternative Approaches

  • Use create_merge_request which seems to handle large content better
  • Split large issues into main issue + detailed comment
  • Create issue with summary, add details via create_issue_note

🔗 Reproduction Steps

  1. Prepare a markdown description of 3,000+ words with: - Multiple code blocks - Lists and formatting - Headers and sections
  2. Call create_issue with this large description: await mcp__gitlab-git-haley-io__create_issue({ project_id: "john/mcp-server-gitlab", title: "Test Large Issue", description: largeMarkdownContent, labels: ["test"] });
  3. Observe timeout after ~30 seconds

📋 Impact Assessment

User Impact

  • Cannot create comprehensive documentation issues programmatically
  • Detailed feature requests require manual creation
  • Breaks automation workflows for issue creation
  • Forces less detailed issues or manual workarounds

Severity

  • Frequency: Medium (detailed issues are common in active projects)
  • Impact: High (blocks automation, requires manual intervention)
  • Workaround: Available but inconvenient

🎯 Acceptance Criteria for Fix

  • Create issue with 5,000+ word descriptions successfully
  • Timeout configuration is exposed and configurable
  • Progress indication for long operations
  • Clear error messages when timeouts occur
  • Retry logic for timeout scenarios
  • Document size limitations in tool description

🧪 Testing Recommendations

  1. Unit Tests: Mock long-running GitLab API calls
  2. Integration Tests: Test with various content sizes
  3. Timeout Tests: Verify timeout handling and retries
  4. Performance Tests: Measure operation time vs content size

📚 References

🏷️ Additional Context

  • This issue was discovered while creating detailed feature requests
  • The same content works fine when pasted into GitLab web UI
  • Merge request creation with similar content seems unaffected
  • This suggests the issue is specific to the create_issue implementation

Note: This is not a GitLab API limitation as the web UI handles the same content without issues. The timeout appears to be in the MCP server layer or its HTTP client configuration.

This issue report documents the timeout problem comprehensively and provides actionable information for fixing it. The workaround of manual creation is reasonable but the issue should be fixed for better automation support.

Edited by John Haley