Troubleshooting Common Issues

This guide helps you resolve common issues you might encounter while working with Agility CMS.

Content Not Appearing

Issue: Content item is saved but not showing on the page

Possible causes:

Content item is not published
Component is not linking to the content item correctly
Page is not published
Cache needs to be cleared

Solutions:

Check that the content item status is "Published"
Verify the component is linking to the correct content item
Ensure the page containing the component is published
Clear browser cache or wait for cache to refresh

Components Not Loading

Issue: Component appears broken or doesn't display

Possible causes:

Component model not properly configured
Required fields not filled
Linked content missing
Component not registered in frontend

Solutions:

Check that all required component fields are filled
Verify linked content items exist and are published
Check component model definition
Contact developer if component appears to be missing from frontend

Publishing Issues

Issue: Can't publish content

Possible causes:

Missing required fields
Insufficient permissions
Approval workflow blocking publication
Validation errors

Solutions:

Check that all required fields are completed
Verify your role has "Publish" permission
Check if approval is required (submit for approval instead)
Review any validation error messages

Permission Problems

Issue: Can't access or edit content

Possible causes:

Insufficient permissions for your role
Content is restricted by Security settings
Role doesn't have access to specific content lists

Solutions:

Check your role and permissions
Contact administrator to review Security settings
Verify you have access to the content list or page

Image Upload Issues

Issue: Images not uploading or displaying

Possible causes:

File size too large
Unsupported file format
Upload permissions
CDN delivery issues

Solutions:

Check file size limits
Verify file format is supported (JPG, PNG, GIF, WebP, SVG)
Check upload permissions
Wait for CDN propagation if recently uploaded

Search Not Finding Content

Issue: Search doesn't return expected results

Possible causes:

Content not published
Search indexing delay
Incorrect search terms

Solutions:

Ensure content is published
Wait a moment for search index to update
Try different search terms
Use filters to narrow results

Page Not Updating

Issue: Changes to page not appearing

Possible causes:

Page not published
Browser cache
CDN cache
Component changes not saved

Solutions:

Verify page is published
Clear browser cache
Wait for CDN cache to refresh
Check that all component changes were saved

Linked Content Issues

Issue: Linked content not displaying correctly

Possible causes:

Linked content item not published
Wrong content item linked
Component not configured to display linked content

Solutions:

Verify linked content item is published
Check that correct content item is linked
Review component configuration

Getting Help

If you encounter issues not covered here:

Check documentation: Review relevant guides
Contact administrator: For permission or configuration issues
Contact developer: For component or frontend issues
Review error messages: Error messages often provide helpful clues

Prevention Tips

Save frequently: Don't lose work
Preview before publishing: Catch issues early
Check permissions: Understand what you can and can't do
Follow workflows: Respect approval processes
Test changes: Verify changes work as expected