Skip to main content
The MCP tools provide detailed error messages designed to help AI agents understand and correct issues.

​
Project Context Errors

​
NO_PROJECT_CONTEXT

Returned when no project context is set and no projectId parameter is provided. 
{
  "error": {
    "code": "NO_PROJECT_CONTEXT",
    "message": "No project context set. Use set_project to set a default project or provide projectId parameter.",
    "hint": "The project_context prompt provides available projects and guidance."
  }
}
Recovery: Call set_project with a valid project ID, or include projectId in the tool call.

​
PROJECT_ACCESS_DENIED

Returned when the user doesn’t have access to the specified project. 
{
  "error": {
    "code": "PROJECT_ACCESS_DENIED",
    "message": "You do not have access to project proj_999",
    "hint": "Use list_projects to see available projects."
  }
}
Recovery: Use list_projects to find projects you have access to.

​
Content Validation Errors

The create_content and update_content tools validate all content against the content type’s JSON schema.

​
VALIDATION_ERROR

General validation failure with detailed error information. 
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Content validation failed against content type schema",
    "details": {
      "contentTypeId": "ct_story_001",
      "contentTypeVersion": 2,
      "validationErrors": [
        {
          "path": "/components/0/text",
          "schemaPath": "#/definitions/StoryParagraph/properties/text",
          "keyword": "maxLength",
          "message": "Text must not exceed 10000 characters",
          "params": {
            "limit": 10000,
            "actual": 10523
          },
          "suggestion": "Reduce text length by 523 characters or split into multiple paragraphs"
        }
      ]
    }
  }
}

​
SCHEMA_STRUCTURE_ERROR

Using components or fields not allowed by the content type. 
{
  "error": {
    "code": "SCHEMA_STRUCTURE_ERROR",
    "message": "Content structure does not match content type schema",
    "details": {
      "validationErrors": [
        {
          "path": "/components/2",
          "message": "Invalid component type 'StoryVideo' - not in allowed components list",
          "allowedTypes": ["StoryParagraph", "StoryPhoto", "StoryPhotoGallery", "StorySubheader"],
          "suggestion": "Use one of the allowed component types for this content type"
        }
      ]
    }
  }
}
Recovery: Check the content type schema for allowed component types.

​
REQUIRED_FIELD_ERROR

Missing mandatory fields. 
{
  "error": {
    "code": "REQUIRED_FIELD_ERROR",
    "message": "Required fields are missing",
    "details": {
      "validationErrors": [
        {
          "path": "/title",
          "message": "Required field 'title' is missing",
          "suggestion": "Add a 'title' field with a string value (1-200 characters)"
        },
        {
          "path": "/components",
          "message": "Required field 'components' is missing",
          "suggestion": "Add a 'components' array with at least one component"
        }
      ]
    }
  }
}
Recovery: Add all required fields as specified in the schema.

​
TYPE_MISMATCH_ERROR

Incorrect data types. 
{
  "error": {
    "code": "TYPE_MISMATCH_ERROR",
    "message": "Field types do not match schema requirements",
    "details": {
      "validationErrors": [
        {
          "path": "/components/0/asset/id",
          "message": "Expected string, got number",
          "expected": "string",
          "actual": "number",
          "value": 12345,
          "suggestion": "Provide asset ID as a string, e.g., \"asset-12345\""
        }
      ]
    }
  }
}
Recovery: Convert the value to the expected type.

​
CONSTRAINT_VIOLATION

Exceeding limits or breaking rules. 
{
  "error": {
    "code": "CONSTRAINT_VIOLATION",
    "message": "Content violates schema constraints",
    "details": {
      "validationErrors": [
        {
          "path": "/subtitle",
          "keyword": "maxLength",
          "message": "Subtitle exceeds maximum length of 100 characters",
          "params": {
            "limit": 100,
            "actual": 125
          },
          "suggestion": "Shorten subtitle to 100 characters or less"
        }
      ]
    }
  }
}
Recovery: Adjust the value to meet the constraint.

​
ASSET_NOT_FOUND

Referencing non-existent assets. 
{
  "error": {
    "code": "ASSET_NOT_FOUND",
    "message": "Referenced assets do not exist",
    "details": {
      "validationErrors": [
        {
          "path": "/asset/id",
          "message": "Asset 'asset-999' not found in project",
          "assetId": "asset-999",
          "suggestion": "Use search_assets to find a valid asset ID. Assets must be uploaded through the CMS interface before use."
        }
      ]
    }
  }
}
Recovery: Use search_assets to find valid asset IDs.

​
MULTIPLE_VALIDATION_ERRORS

Multiple errors grouped and summarized. 
{
  "error": {
    "code": "MULTIPLE_VALIDATION_ERRORS",
    "message": "Multiple validation errors found",
    "summary": {
      "total": 5,
      "byCategory": {
        "missingRequired": 2,
        "invalidType": 1,
        "constraintViolation": 2
      }
    },
    "details": {
      "validationErrors": [
        { "..." : "..." }
      ]
    }
  }
}

​
Recovery Strategies

When encountering validation errors:
  1. Parse the suggestion field: Every error includes actionable guidance
  2. Review the schema: Use get_content_type to understand requirements
  3. Fix asset issues: Use search_assets to find valid asset IDs
  4. Handle length constraints: Split long content into multiple components
  5. Check component types: Ensure using only allowed component types

​
Error Prevention Best Practices

1

Fetch the schema first

Always use get_content_type before creating content to understand the structure and constraints.
2

Validate asset IDs

Use search_assets to verify assets exist before referencing them.
3

Check length limits

Review maxLength constraints in the schema for all text fields.
4

Use correct component types

Match component type names exactly as defined in the schema’s definitions.
5

Include all required fields

Check the schema’s required arrays at each level of the structure.