# Admin Troubleshooting

> Source: https://agilitycms.com/docs/training-guide/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. Open the webhook's **History** to see whether the delivery was attempted and what your endpoint returned
3. Verify cache tags are correct
4. Check that your handler returns a 2xx quickly — the delivery timeout is 30 seconds, so a slow endpoint reads as a failed one
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

### Start with Delivery History

Every webhook has a **History** action in **Settings → Webhooks**. It lists each delivery attempt with the HTTP status your endpoint returned, which attempt it was, when the next retry is due, and the payload and response bodies. Check it before anything else — it usually answers the question outright.

> Delivery history is **go-forward only**. A webhook created before this feature shipped shows an empty history until it fires again. That is expected, not a fault.

### Issue: Webhook Not Firing

**Solutions:**
1. Verify webhook URL is correct and publicly accessible
2. Check webhook is enabled
3. Verify the right event categories are selected
4. Open **History** to see whether Agility attempted a delivery and what came back
5. Test webhook endpoint manually

### Issue: Deliveries Failing or Being Retried

**Solutions:**
1. Check the response code and error in **History** — success is any 2xx; anything else is a failure
2. **Redirects count as failures.** Agility does not follow them — point the webhook at its final URL
3. The delivery timeout is **30 seconds**. Acknowledge with a 2xx immediately and do the real work in the background
4. Enable **retries** on the webhook if a transient failure should be attempted again

### Issue: Signature Verification Failing

> ⚠️ **There is no webhook "security key."** Agility does not send `AGILITY_SECURITY_KEY`, an `x-agility-security-key` header, or any other shared secret with a webhook — that key is used for **preview** authentication and is unrelated. Earlier guidance here described a validation check that could never succeed, because the header it looked for was never sent. Use **secure delivery** instead.

**Solutions:**
1. Confirm **Enable secure delivery** is switched on for that webhook
2. Verify against the **raw request body** — a JSON body parser that re-serializes the payload will break the signature
3. Accept **any** matching signature in the header — two space-separated signatures are sent during the 24 hours after a secret roll
4. Confirm your stored secret matches the one on the webhook; roll it if in doubt
5. See [Verifying Signed Webhooks](/docs/developers/verifying-signed-webhooks) for the header format and verification samples

### Issue: The Same Event Arrives Twice

Delivery is **at-least-once** by design. Use the `webhook-id` header as an idempotency key — it is unique per event, stable across retries, and sent on every delivery whether signed or not.

## Best Practices for Troubleshooting

1. **Check Logs**: Review error logs and a webhook's delivery History
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