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 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