Error Codes¶

Complete reference for all error codes returned by Code Scalpel tools.

Error Code Format¶

Error codes follow the pattern: CATEGORY_SPECIFIC_ERROR

{
  "error": {
    "code": "SYMBOL_NOT_FOUND",
    "message": "Function 'process_ordder' not found",
    "suggestion": "Did you mean 'process_order'?",
    "recovery_options": ["process_order"]
  }
}

Error Categories¶

Category	Description
`PARSE_*`	Parsing and syntax errors
`SYMBOL_*`	Symbol lookup errors
`FILE_*`	File system errors
`TIER_*`	License and tier errors
`TIMEOUT_*`	Timeout errors
`CONFIG_*`	Configuration errors
`SECURITY_*`	Security-related errors

Parse Errors¶

PARSE_ERROR¶

Code could not be parsed.

{
  "code": "PARSE_ERROR",
  "message": "Failed to parse Python code",
  "line": 15,
  "column": 8,
  "suggestion": "Check for syntax errors near line 15"
}

Causes: - Invalid syntax - Unsupported language features - Encoding issues

Solutions: - Fix syntax errors - Ensure code is valid for specified language - Use UTF-8 encoding

PARSE_LANGUAGE_UNSUPPORTED¶

Language not supported.

{
  "code": "PARSE_LANGUAGE_UNSUPPORTED",
  "message": "Language 'cobol' is not supported",
  "supported_languages": ["python", "javascript", "typescript", "java"]
}

Symbol Errors¶

SYMBOL_NOT_FOUND¶

Requested symbol doesn't exist.

{
  "code": "SYMBOL_NOT_FOUND",
  "message": "Function 'procss_order' not found",
  "suggestion": "Did you mean 'process_order'?",
  "recovery_options": ["process_order", "process_orders"],
  "file": "services/order.py"
}

Solutions: - Check spelling - Verify symbol exists in file - Use suggested alternatives

SYMBOL_AMBIGUOUS¶

Multiple symbols match the name.

{
  "code": "SYMBOL_AMBIGUOUS",
  "message": "Multiple symbols named 'process' found",
  "matches": [
    {"type": "function", "file": "utils.py", "line": 10},
    {"type": "method", "file": "handler.py", "line": 45}
  ],
  "suggestion": "Specify the file path to disambiguate"
}

SYMBOL_TYPE_MISMATCH¶

Symbol exists but is wrong type.

{
  "code": "SYMBOL_TYPE_MISMATCH",
  "message": "Expected function but 'User' is a class",
  "expected_type": "function",
  "actual_type": "class"
}

File Errors¶

FILE_NOT_FOUND¶

File doesn't exist.

{
  "code": "FILE_NOT_FOUND",
  "message": "File 'src/utils.py' not found",
  "suggestion": "Did you mean 'src/util.py'?",
  "searched_paths": ["/project/src/utils.py"]
}

FILE_ACCESS_DENIED¶

Permission denied.

{
  "code": "FILE_ACCESS_DENIED",
  "message": "Cannot read file: permission denied",
  "file": "/etc/passwd"
}

FILE_OUTSIDE_PROJECT¶

Path traversal detected.

{
  "code": "FILE_OUTSIDE_PROJECT",
  "message": "Path is outside project root",
  "path": "/etc/passwd",
  "project_root": "/project"
}

FILE_TOO_LARGE¶

File exceeds size limit.

{
  "code": "FILE_TOO_LARGE",
  "message": "File exceeds maximum size",
  "file_size": 15000000,
  "max_size": 10000000,
  "tier": "community"
}

Tier Errors¶

TIER_FEATURE_UNAVAILABLE¶

Feature requires higher tier.

{
  "code": "TIER_FEATURE_UNAVAILABLE",
  "message": "Cross-file security scan requires Pro tier",
  "current_tier": "community",
  "required_tier": "pro",
  "upgrade_url": "https://codescalpel.dev/pricing"
}

TIER_LIMIT_EXCEEDED¶

Tier limit reached.

{
  "code": "TIER_LIMIT_EXCEEDED",
  "message": "Maximum depth of 3 exceeded",
  "limit_name": "max_depth",
  "limit_value": 3,
  "requested_value": 10,
  "tier": "community"
}

TIER_LICENSE_INVALID¶

License validation failed.

{
  "code": "TIER_LICENSE_INVALID",
  "message": "License file is invalid or expired",
  "reason": "expired",
  "expiration_date": "2025-01-01"
}

Timeout Errors¶

TIMEOUT_ANALYSIS¶

Analysis timed out.

{
  "code": "TIMEOUT_ANALYSIS",
  "message": "Analysis timed out after 120 seconds",
  "timeout_ms": 120000,
  "partial_results": true
}

TIMEOUT_SYMBOLIC¶

Symbolic execution timed out.

{
  "code": "TIMEOUT_SYMBOLIC",
  "message": "Symbolic execution exceeded time limit",
  "paths_explored": 150,
  "paths_remaining": "unknown"
}

Configuration Errors¶

CONFIG_INVALID¶

Configuration file is invalid.

{
  "code": "CONFIG_INVALID",
  "message": "Invalid configuration in limits.toml",
  "file": ".code-scalpel/limits.toml",
  "line": 15,
  "detail": "Expected integer for max_depth"
}

CONFIG_MISSING¶

Required configuration missing.

{
  "code": "CONFIG_MISSING",
  "message": "Required configuration file not found",
  "file": ".code-scalpel/governance.yaml"
}

CONFIG_TAMPERED¶

Policy file integrity check failed.

{
  "code": "CONFIG_TAMPERED",
  "message": "Policy file has been modified",
  "file": "limits.toml",
  "expected_hash": "sha256:abc...",
  "actual_hash": "sha256:xyz..."
}

Security Errors¶

SECURITY_PATH_TRAVERSAL¶

Path traversal attempt detected.

{
  "code": "SECURITY_PATH_TRAVERSAL",
  "message": "Attempted path traversal detected",
  "path": "../../../etc/passwd"
}

SECURITY_INJECTION_DETECTED¶

Potentially malicious input.

{
  "code": "SECURITY_INJECTION_DETECTED",
  "message": "Potentially malicious input detected",
  "input_type": "code",
  "detail": "Suspicious pattern in input"
}

Oracle Recovery¶

The Oracle middleware automatically attempts recovery for many errors:

{
  "error": {
    "code": "SYMBOL_NOT_FOUND",
    "message": "Function 'procss_order' not found"
  },
  "oracle_recovery": {
    "attempted": true,
    "method": "fuzzy_match",
    "suggested": "process_order",
    "confidence": 0.95
  }
}

Recoverable Errors¶

Error Code	Recovery Method
`SYMBOL_NOT_FOUND`	Fuzzy matching
`FILE_NOT_FOUND`	Path suggestion
`PARSE_ERROR`	Syntax hint
`TIER_LIMIT_EXCEEDED`	Partial results

Handling Errors¶

Python Example¶

def handle_tool_response(response):
    if response.get("error"):
        error = response["error"]
        code = error["code"]

        if code == "SYMBOL_NOT_FOUND":
            if error.get("recovery_options"):
                # Use first suggestion
                return retry_with(error["recovery_options"][0])

        elif code == "TIER_LIMIT_EXCEEDED":
            # Partial results may be available
            if response.get("data"):
                return response["data"]

        raise ToolError(error["message"])

    return response["data"]

TypeScript Example¶

function handleError(error: ErrorDetails): void {
  switch (error.code) {
    case "SYMBOL_NOT_FOUND":
      if (error.suggestion) {
        console.log(`Did you mean: ${error.suggestion}?`);
      }
      break;

    case "TIER_FEATURE_UNAVAILABLE":
      console.log(`Upgrade required: ${error.required_tier}`);
      break;

    default:
      console.error(error.message);
  }
}