This guide covers common administrative issues and how to resolve them.

# Admin Troubleshooting

This guide covers common administrative issues and how to resolve them.

## Common Issues

### Issue: Component Not Appearing

**Symptoms:**
- Component not showing on page
- Component name not found error

**Solutions:**
1. Check component name matches frontend registration (case-insensitive)
2. Verify component is saved and published
3. Check user permissions (Designer role needed for component management)
4. Verify component is registered in frontend code

### Issue: Content Not Loading

**Symptoms:**
- Content not appearing in application
- API returns 404 or empty results

**Solutions:**
1. Verify API keys are correct
2. Check content is published (not just saved as draft)
3. Verify locale matches content locale
4. Check content model exists and is configured correctly
5. Verify reference names are correct

### Issue: Permission Denied

**Symptoms:**
- User cannot access content or features
- Permission errors in interface

**Solutions:**
1. Check user's assigned role (Reader, Contributor, Editor, etc.)
2. Verify item-level permissions for specific content models
3. Check if user has appropriate permission (Read, Edit, Publish, etc.) for the action
4. Ensure user has "Contribute" permission if trying to edit their own content
5. Verify "Design/Develop" permission if accessing designer-only fields

### Issue: API Errors

**Symptoms:**
- API calls failing
- 401 Unauthorized errors
- 404 Not Found errors

**Solutions:**
1. Verify API keys are valid
2. Check network connectivity
3. Review API rate limits
4. Check webhook configuration
5. Verify instance GUID is correct

### Issue: Cache Not Invalidating

**Symptoms:**
- Content not updating after publish
- Stale content appearing

**Solutions:**
1. Verify webhook is configured correctly
2. Check webhook security key matches
3. Verify cache tags are correct
4. Check webhook logs for errors
5. Manually revalidate cache if needed

### Issue: Preview Not Working

**Symptoms:**
- Preview mode not showing draft content
- Preview key errors

**Solutions:**
1. Verify preview API key is set
2. Check preview endpoint is accessible
3. Verify draft mode is enabled
4. Check preview key validation
5. Ensure preview key hasn't been regenerated

## User Management Issues

### Issue: User Cannot Access Instance

**Solutions:**
1. Check user role is not "None"
2. Verify user is active
3. Check user email is correct
4. Verify user has been invited

### Issue: User Has Wrong Permissions

**Solutions:**
1. Review user's assigned role
2. Check item-level permissions
3. Verify role permissions match user's needs
4. Update role assignment if needed

## Content Model Issues

### Issue: Content Model Not Saving

**Solutions:**
1. Check required fields are filled
2. Verify field names are valid
3. Check for validation errors
4. Ensure user has Designer permission

### Issue: Content Model Changes Not Appearing

**Solutions:**
1. Verify changes are saved
2. Check if content model is published
3. Clear cache if needed
4. Verify frontend code matches model structure

## Component Model Issues

### Issue: Component Not Matching Frontend

**Solutions:**
1. Verify component name matches frontend registration (case-insensitive)
2. Check field names match TypeScript interfaces
3. Ensure component is registered in frontend
4. Coordinate with developers on component registration

## API Key Issues

### Issue: Invalid API Key

**Solutions:**
1. Verify key is correct (no typos or extra spaces)
2. Check correct key type (fetch vs preview)
3. Ensure key hasn't been regenerated
4. Update environment variables if key was regenerated

### Issue: API Key Exposed

**Solutions:**
1. Regenerate compromised key immediately
2. Update all applications using the key
3. Review access logs for unauthorized usage
4. Update environment variables

## Webhook Issues

### Issue: Webhook Not Firing

**Solutions:**
1. Verify webhook URL is correct and accessible
2. Check webhook is enabled
3. Verify events are selected
4. Check webhook logs in Agility CMS
5. Test webhook endpoint manually

### Issue: Webhook Validation Failing

**Solutions:**
1. Verify security key matches
2. Check header name is correct (`x-agility-security-key`)
3. Ensure key hasn't been regenerated
4. Test webhook validation logic

## Best Practices for Troubleshooting

1. **Check Logs**: Review error logs and webhook logs
2. **Verify Configuration**: Double-check all configurations
3. **Test Incrementally**: Test changes one at a time
4. **Document Issues**: Document problems and solutions
5. **Coordinate with Team**: Work with developers and content editors


Administrators

Admin Troubleshooting

System Status

Privacy Policy

GDPR

Security

Glossary

Headless CMS

Composable DXP

Enterprise

Marketers

Developers

Features

Roadmap

Pricing

Platform

App Marketplace

Ecosystem Partners

MACH Alliance Member

Case Studies

Solutions on Agility

Customers & Partners 

ROI Calculator

Resource Center

Documentation

Blog

Starters

Headless CMS Comparison

Resources

100% Canadian

Leadership

Core Values

Events

Careers

Contact Us

About Us

G2 Reviews

YouTube

Instagram

Slack Community

Subscribe to our Newsletter

Overview

Editors

Owners & Admins

Training Guide

Apps

<p>What is your developer-dependent CMS actually costing you? <a class="link-line line-purple" href="/Developer-Dependent-CMS-Calculator" rel="noopener">Calculate your costs and get a full report</a></p>

##Title##

training-articles

admin-troubleshooting