Skip to main content
POST
/
tools
/
get_diagnostics
Get Diagnostics
curl --request POST \
  --url https://api.example.com/tools/get_diagnostics
{
  "diagnostics": [
    {
      "range": {
        "start": {},
        "end": {}
      },
      "severity": 123,
      "code": "<string>",
      "message": "<string>",
      "source": "<string>"
    }
  ],
  "errorCount": 123,
  "warningCount": 123
}

​
Overview

Get real-time diagnostics (errors, warnings, and informational messages) for your Python code. This provides the same error detection you see in your IDE’s Problems panel.

​
Request

​
uri
string
required
File URI (e.g., file:///workspace/main.py)
​
severity
string
Filter by severity: error, warning, information, hint

​
Response

​
diagnostics
array
Array of diagnostic messages
​
errorCount
number
Total number of errors
​
warningCount
number
Total number of warnings

​
Example Request

curl -X POST https://api.pylancemcp.dev/v1/tools/call \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "get_diagnostics",
    "arguments": {
      "uri": "file:///workspace/app/views.py"
    }
  }'

​
Example Response

{
  "diagnostics": [
    {
      "range": {
        "start": { "line": 15, "character": 8 },
        "end": { "line": 15, "character": 21 }
      },
      "severity": 1,
      "code": "undefined-variable",
      "message": "\"undefined_var\" is not defined",
      "source": "Pylance"
    },
    {
      "range": {
        "start": { "line": 23, "character": 12 },
        "end": { "line": 23, "character": 26 }
      },
      "severity": 2,
      "code": "type-mismatch",
      "message": "Argument of type \"str\" cannot be assigned to parameter \"amount\" of type \"int\" in function \"calculate\"",
      "source": "Pylance"
    },
    {
      "range": {
        "start": { "line": 42, "character": 0 },
        "end": { "line": 42, "character": 6 }
      },
      "severity": 3,
      "code": "unused-import",
      "message": "Import \"typing\" is not accessed",
      "source": "Pylance"
    }
  ],
  "errorCount": 1,
  "warningCount": 1
}

​
Diagnostic Types

​
Errors (Severity 1)

CodeDescriptionExample
undefined-variableVariable not definedprint(unknown_var)
type-mismatchType doesn’t match expectedcalculate("5") when expecting int
import-not-foundModule cannot be importedimport nonexistent_module
syntax-errorInvalid Python syntaxdef foo( (missing closing paren)
missing-argumentRequired parameter not providedcalculate() when calculate(x) expected

​
Warnings (Severity 2)

CodeDescriptionExample
unused-importImport never usedimport os but os not referenced
unused-variableVariable assigned but never usedtemp = 5 but temp not used
duplicate-importModule imported multiple timesimport json twice
unreachable-codeCode that will never executeCode after return
deprecatedUsing deprecated functionalitycollections.Mapping instead of collections.abc.Mapping

​
Information (Severity 3)

CodeDescriptionExample
missing-type-hintType annotation missingdef foo(x): instead of def foo(x: int):
convention-violationStyle guideline not followedFunction name not snake_case

​
Use Cases

​
Pre-Commit Validation

# Check for errors before committing
files_to_check = get_changed_files()

for file in files_to_check:
    diagnostics = client.get_diagnostics(uri=file)
    
    if diagnostics.error_count > 0:
        print(f"❌ Cannot commit: {file} has errors")
        for diag in diagnostics.diagnostics:
            if diag.severity == 1:
                print(f"  Line {diag.range.start.line + 1}: {diag.message}")
        exit(1)

print("✅ All files are error-free")

​
Continuous Monitoring

# Watch for new errors as code changes
def monitor_file(file_uri):
    previous_errors = set()
    
    while True:
        diagnostics = client.get_diagnostics(uri=file_uri)
        current_errors = {
            (d.range.start.line, d.message) 
            for d in diagnostics.diagnostics 
            if d.severity == 1
        }
        
        # New errors appeared
        new_errors = current_errors - previous_errors
        if new_errors:
            for line, message in new_errors:
                print(f"🚨 New error at line {line + 1}: {message}")
        
        previous_errors = current_errors
        time.sleep(2)

​
Code Quality Metrics

# Calculate code quality score
def calculate_quality_score(workspace_files):
    total_errors = 0
    total_warnings = 0
    
    for file in workspace_files:
        diagnostics = client.get_diagnostics(uri=file)
        total_errors += diagnostics.error_count
        total_warnings += diagnostics.warning_count
    
    # Score: 100 - (10 * errors) - (2 * warnings)
    score = max(0, 100 - (10 * total_errors) - (2 * total_warnings))
    
    return {
        "score": score,
        "errors": total_errors,
        "warnings": total_warnings,
        "grade": "A" if score >= 90 else "B" if score >= 80 else "C"
    }

​
Filtering by Severity

Get only specific severity levels: 
diagnostics = client.get_diagnostics(
    uri="file:///workspace/app/views.py",
    severity="error"
)

# Only severity 1 (errors) returned

​
Performance Tips

Incremental Updates: Only check files that changed, not entire workspace
Debounce Checks: Wait 500ms-1s after typing stops before checking
Cache Results: Diagnostics don’t change unless file changes

​
Error Responses

CodeReasonSolution
FILE_NOT_FOUNDFile doesn’t existVerify file path
INVALID_PYTHONFile is not PythonCheck file extension and content
PARSE_ERRORCannot parse fileFile has syntax errors preventing analysis
WORKSPACE_NOT_LOADEDWorkspace still loadingWait for initialization

​
Rate Limits

TierRequests/HourRequests/Day
Free20100
Hobby5005,000
Pro5,00050,000
EnterpriseUnlimitedUnlimited

Get Code Actions

Get quick fixes for diagnostics

Format Document

Auto-format code to fix style issues

Get Hover

Get more info about errors

Apply Workspace Edit

Apply fixes automatically