Error Handling

Developer Documentation

For the complete technical reference, see docs/error-handling.md in the repository.

GitLab MCP Server provides structured error handling that classifies errors, extracts actionable details from GitLab API responses, and suggests corrective actions to the AI assistant.

Error classification

Every error from the GitLab API is classified by HTTP status code into an actionable message:

Status Code	Classification	Message
400	Bad request	Check your input parameters
401	Authentication	GITLAB_TOKEN may be invalid or expired
403	Permissions	Your token lacks the required permissions
404	Not found	The resource does not exist or you lack access
409	Conflict	The resource already exists or there is a state conflict
422	Validation	GitLab rejected the request due to invalid data
429	Rate limit	Too many requests — wait before retrying
500	Server error	GitLab internal server error
502	Bad gateway	GitLab is temporarily unavailable
503	Maintenance	GitLab is under maintenance or overloaded

Network-level errors are also classified:

Error Type	Message
Connection refused	GitLab server is unreachable
DNS failure	GitLab server hostname could not be resolved
Timeout	Request to GitLab timed out
TLS/SSL	TLS/SSL handshake failed

Error wrapping functions

The server uses five error handling helpers, chosen based on the operation type:

WrapErr

Read-only operations — Used for list, get, and search operations. Classifies the error and wraps it with the operation name:

list_issues: authentication failed — GITLAB_TOKEN may be invalid or expired

WrapErrWithMessage

Mutating operations — Used for create, update, and delete operations. Includes the specific error detail extracted from the GitLab API response:

fileCreate: bad request — A file with this name already exists: POST .../files: 400

The server extracts the detailed error message from GitLab’s API response, handling nested formats like {message: {base: [text]}}, and truncates at 300 characters.

WrapErrWithHint

Known corrective actions — Used when the corrective action for a specific error is known. Appends an actionable suggestion:

branchProtect: conflict — Protected branch rule already exists.
Suggestion: use gitlab_protected_branch_get to view current rules

Decision tree

Scenario	Function
Read-only operation (list, get, search)	WrapErr
Mutating operation (create, update, delete)	WrapErrWithMessage
Specific error with known fix	WrapErrWithHint
Status-specific hint (single code)	WrapErrWithStatusHint
Get operation returning 404	NotFoundResult

flowchart TD
    A[Error Occurred] --> B{Operation type?}
    B -->|list / get / search| C{Is HTTP 404<br/>on GET?}
    C -->|Yes| D[NotFoundResult]
    C -->|No| E[WrapErr]
    B -->|create / update / delete| F{Known fix<br/>for this error?}
    F -->|Yes| G{Specific HTTP<br/>status code?}
    G -->|Yes| H[WrapErrWithStatusHint]
    G -->|No| I[WrapErrWithHint]
    F -->|No| J[WrapErrWithMessage]

    style D fill:#3b82f6,color:#fff
    style E fill:#6b7280,color:#fff
    style H fill:#f59e0b,color:#000
    style I fill:#f59e0b,color:#000
    style J fill:#ef4444,color:#fff

NotFoundResult — Informational 404 responses

For get handlers, 404 errors are treated as informational rather than failures. Instead of returning an opaque Go error (logged at ERROR level), the handler returns a CallToolResult with IsError: true and domain-specific hints:

## ❓ Branch Not Found

Branch `feature/old` was not found in the project.

💡 **Next steps:**

- Use `gitlab_list_branches` to see available branches
- Check branch name spelling and case sensitivity

This pattern is applied to all 27 get handlers across 21 domains. It logs at INFO level (expected outcome) and provides the AI assistant with actionable next steps.

Validation hints

For 422 validation errors, the server automatically enriches the error with guidance based on pattern matching. Over 15 common patterns are recognized, including:

• Missing required fields
• Invalid date formats
• Name/title length limits
• Duplicate resource names
• Invalid enum values

These hints help the AI assistant correct its request without additional API calls.

Error response format

When a tool encounters an error, the response is formatted as a Markdown block with structured diagnostic fields:

## ❌ Error: list_branches

**Status**: 401 Unauthorized
**Detail**: authentication failed — GITLAB_TOKEN may be invalid or expired
**Request ID**: abc123def456

💡 **Suggestion**: Check that your token is valid and has the `api` scope.

The structured response includes:

Field	Description
Operation	The tool action that failed
Status	HTTP status code and classification
Detail	Specific error message from GitLab
Request ID	GitLab’s X-Request-Id for support tickets
Suggestion	Actionable hint (when available)

Transient vs permanent errors

Do not retry permanent errors

4xx errors (except 429) indicate a problem with the request itself — retrying will produce the same result. Fix the input parameters or configuration instead.

The server classifies errors as transient (retryable) or permanent:

Type	Status Codes	Behavior
Transient	429, 5xx, timeouts, connection refused	Safe to retry after a delay
Permanent	4xx (except 429)	Do not retry — fix the input or configuration

Example error scenarios

Invalid token

❌ list_projects: authentication failed — GITLAB_TOKEN may be invalid or expired
💡 Generate a new token with api scope at GitLab → Preferences → Access Tokens

Permission denied

❌ create_issue: access denied — your token lacks the required permissions
Detail: 403 Forbidden
💡 Ensure the token has api scope and you have Developer+ access to the project

Resource conflict

❌ branchProtect: conflict — Protected branch rule already exists
💡 Use gitlab_protected_branch_get to view current rules, or gitlab_protected_branch_update to modify

Validation error

❌ create_issue: validation failed — title is too long (maximum is 255 characters)
💡 Shorten the title to 255 characters or less

Frequently asked questions

How does the server classify GitLab API errors?

GitLab MCP Server classifies every API error by HTTP status code into an actionable message: 401 signals an invalid or expired GITLAB_TOKEN, 403 signals missing permissions, 404 a missing resource or lack of access, 422 a validation failure, and 429 a rate limit. Network-level failures — connection refused, DNS failure, timeout, and TLS handshake errors — are classified separately. The classification drives both the wrapped error message and whether the failure is treated as retryable.

Which error wrapping function is used for which operation?

Read-only operations (list, get, search) use WrapErr. Mutating operations (create, update, delete) use WrapErrWithMessage, which includes the specific detail extracted from the GitLab response. When a corrective action is known, WrapErrWithHint appends a suggestion, and WrapErrWithStatusHint scopes that hint to a single HTTP status code. A get operation returning 404 uses NotFoundResult instead of returning an error.

Why does a 404 not appear as an error?

For get handlers, 404 responses are treated as informational rather than failures. Instead of returning an opaque Go error logged at ERROR level, the handler returns a CallToolResult with IsError: true and domain-specific hints, logged at INFO level. This NotFoundResult pattern is applied to all 27 get handlers across 21 domains and gives the AI assistant actionable next steps, such as listing available resources or checking the resource name.

Should the AI assistant retry a failed operation?

It depends on whether the error is transient or permanent. Transient errors — 429, 5xx, timeouts, and connection refused — are safe to retry after a delay. Permanent errors — 4xx except 429 — indicate a problem with the request itself, so retrying produces the same result. For permanent errors, fix the input parameters or configuration instead of retrying.