Error Codes

This guide documents all error codes you may encounter during widget publishing and how to resolve them.

Error Code Overview

Each error includes:

• Code: Unique identifier for the error
• Stage: When the error occurs (validation, fetch, transformation, upload)
• Retryable: Whether the error may resolve on retry

Validation Errors

These errors occur during schema validation and configuration checks. They are not retryable — you must fix the underlying issue.

PATH_TRAVERSAL_DETECTED

Message: Path traversal detected in source.path/entry

Cause: The source.path or source.entry field contains ../ which could access files outside the widget directory.

Fix: Use relative paths without ../:

// Wrong
"source": {
  "path": "../shared/widget",
  "entry": "index.html"
}

// Correct
"source": {
  "path": "widgets/my-widget",
  "entry": "index.html"
}

---

ABSOLUTE_PATH_NOT_ALLOWED

Message: Absolute paths are not allowed in source.path

Cause: The source.path field starts with /, making it an absolute path.

Fix: Use a relative path from the repository root:

// Wrong
"source": {
  "path": "/widgets/my-widget",
  "entry": "index.html"
}

// Correct
"source": {
  "path": "widgets/my-widget",
  "entry": "index.html"
}

---

INVALID_SOURCE_SCHEMA

Message: Invalid source block schema

Cause: The source block is missing required fields or has invalid field types.

Fix: Ensure both path and entry are non-empty strings:

"source": {
  "path": "widgets/my-widget",  // Required: string
  "entry": "index.html"         // Required: string
}

---

ENTRY_FILE_NOT_FOUND

Message: Entry file not found at source.path/source.entry

Cause: The HTML file specified in source.entry doesn't exist in the source.path directory.

Fix:

1. Verify the file exists in your repository
2. Check for typos in the path or filename
3. Ensure the file is committed to the watched branch

widgets/my-widget/
├── index.html  ← This file must exist
├── styles.css
└── app.js

---

INVALID_WIDGET_STRUCTURE

Message: Widget structure is invalid — must have either source or content block

Cause: A widget definition has both source and content blocks, or neither. Each widget must define exactly one content delivery method.

Fix: Use exactly ONE of source or content:

// Wrong: both blocks
{
  "source": { "path": "...", "entry": "..." },
  "content": { "endpoint": "...", "method": "GET" }
}

// Wrong: neither block
{
  "version": "1.0.0",
  "title": "My Widget"
  // Missing source AND content
}

// Correct: source only
{
  "source": {
    "path": "widgets/my-widget",
    "entry": "index.html"
  }
}

// Correct: content only (external URL)
{
  "content": {
    "endpoint": "https://example.com/widgets/my-widget.html",
    "method": "GET"
  }
}

---

MAX_FILES_EXCEEDED

Message: Widget directory exceeds maximum file count (limit: 100)

Cause: The source.path directory contains more than 100 files.

Fix:

1. Remove unnecessary files from the widget directory
2. Combine or minify assets where possible
3. Host shared assets externally and reference them by URL
4. Talk to your Gainsight team if you have a legitimate need for more files

---

MAX_SIZE_EXCEEDED

Message: Widget directory exceeds maximum size (limit: 10 MB)

Cause: The total size of all files in source.path exceeds 10 MB.

Fix:

1. Optimize images (compress, use WebP format)
2. Minify CSS and JavaScript
3. Remove unused assets
4. Host large assets externally and reference them by URL

---

CONTENT_SCAN_REJECTED

Message: Widget rejected: content policy violation

Cause: The widget code contains patterns that match a content safety rule. The error message includes the specific categories that triggered the rejection.

Possible categories: crypto_mining, data_exfiltration, phishing_redirect, obfuscation, external_script_loading

Fix:

1. Read the category in the error message
2. Follow the resolution steps in Content Security — How to Resolve Each Category
3. Push the corrected code to trigger a new build

---

Platform Errors

These errors occur during external service interactions. They may be retryable — wait and push again, or talk to your Gainsight team if persistent.

GITHUB_FETCH_FAILED

Message: Failed to fetch files from GitHub

Cause: Unable to download widget files from your GitHub repository.

Possible reasons:

• GitHub API temporarily unavailable
• Repository access revoked
• Network connectivity issues
• Rate limiting

Fix:

1. Check GitHub Status for outages
2. Verify repository access in GitHub app settings
3. Wait a few minutes and push again to trigger a retry
4. Talk to your Gainsight team if the error persists

---

CDN_UPLOAD_FAILED

This error code appears in your build logs and means the platform could not publish your widget content.

Message: Failed to publish widget content

Cause: Unable to publish widget content to the platform.

Possible reasons:

• Storage service temporarily unavailable
• Network issues

Fix:

1. Wait a few minutes and push again to trigger a retry
2. The system will automatically retry on infrastructure failures
3. Talk to your Gainsight team if the error persists after multiple attempts

---

TRANSFORMATION_FAILED

Message: Failed to transform HTML content

Cause: An error occurred while transforming asset references in the HTML entry file.

Possible reasons:

• Malformed HTML that can't be parsed
• Encoding issues

Fix:

1. Validate your HTML file
2. Ensure the file uses UTF-8 encoding
3. Check for unusual characters or invalid markup

Error Stages

Each error includes a stage indicating when it occurred:

Stage	Description	Typical Errors
validation	Schema and configuration checks	PATH_TRAVERSAL, INVALID_WIDGET_STRUCTURE, MAX_FILES_EXCEEDED
fetch	Downloading files from GitHub	GITHUB_FETCH_FAILED, ENTRY_FILE_NOT_FOUND
scan	Content safety checks	CONTENT_SCAN_REJECTED
transformation	Processing HTML content	TRANSFORMATION_FAILED
upload	Publishing content	CDN_UPLOAD_FAILED

Troubleshooting Workflow

1. Read the error code and message — they indicate exactly what's wrong
2. Check the stage — determines where to focus your investigation
3. Review this guide — find the specific error and follow the fix
4. Test locally — validate your JSON and file structure before pushing
5. Push a fix — commit the fix and push to trigger a new build

Getting Help

If you can't resolve an error:

1. Note the error code, message, and widget name
2. Check if it's a retryable error (try again after a few minutes)
3. Review Common Issues for general issues
4. Talk to your Gainsight team with the error details

Next Steps

• Registry Reference — the root of extensions_registry.json
• Widget Definition Reference — widget entry fields
• Troubleshooting — General troubleshooting