Common Issues

This guide covers frequently encountered issues and their solutions. If you can't find your issue here, contact our support team.

Crawling Issues

Crawl finds fewer pages than expected

Possible Causes:

Max pages limit reached
Crawl depth too shallow
Exclude patterns blocking pages
Pages require authentication
JavaScript-rendered content

Solutions:

Increase the Max Pages setting
Increase the Depth setting
Review and adjust exclude patterns
Set up pre-authentication cookies in Test Data
Enable JavaScript execution (enabled by default)

Crawl is very slow

Possible Causes:

Your website has slow response times
Many pages to crawl
Heavy JavaScript on pages
Rate limiting on your server

Solutions:

Reduce max pages for faster results
Use Single Page mode for quick tests
Whitelist AegisRunner IP if you have rate limiting
Contact support for performance optimization

Crawl fails to start

Possible Causes:

Monthly crawl limit reached
Invalid base URL
Website is unreachable

Solutions:

Check your usage in Settings → Usage
Verify your project's base URL is correct
Ensure your website is accessible from the internet
Upgrade your plan if you've reached limits

Forms not detected during crawl

Possible Causes:

Forms rendered by JavaScript after page load
Forms inside iframes
Forms using Shadow DOM
Non-standard form implementations

Solutions:

Wait times are automatic, but complex JS may need more time
Iframes are not currently supported - forms must be in main document
Report Shadow DOM forms to support for future support
Manually create test data for non-detected forms

Test Execution Issues

Tests fail with "Element not found"

Possible Causes:

Selector has changed in your application
Element hasn't loaded yet (timing issue)
Element is hidden or in a different state
Page navigation didn't complete

Solutions:

Check if your application's HTML structure changed
Use more stable selectors (data-testid, IDs)
Add explicit wait conditions
Regenerate tests after significant UI changes

Tests timeout

Possible Causes:

Website is slow to respond
Long-running operations (file uploads, etc.)
Infinite loops or hanging requests
Network issues

Solutions:

Check your website's performance
Increase timeout values for slow operations
Look for JavaScript errors in your application
Check for failing API calls

Tests are flaky (inconsistent results)

Possible Causes:

Race conditions in your application
Time-dependent logic
Shared test state
External dependencies

Solutions:

Add proper wait conditions for async operations
Use test data with deterministic values
Ensure tests are isolated (no shared state)
Mock external services when possible

Authentication issues - tests redirect to login

Possible Causes:

Pre-auth cookies not set or expired
Session expired during test
Cookies set for wrong domain

Solutions:

Update pre-authentication cookies in Test Data
Ensure cookie domain matches your site
Create a login user flow that runs first
Use longer session timeouts for test accounts

Account & Billing Issues

Can't create new projects

Cause: You've reached your plan's project limit.

Solutions:

Delete unused projects
Upgrade to a higher plan
Check your usage: Settings → Usage

Can't invite team members

Cause: Team member limit reached or wrong role.

Solutions:

Check team member limits for your plan
Remove inactive team members
Only Owners and Admins can invite members
Upgrade to Pro or Business for more team members

Payment failed

Possible Causes:

Insufficient funds
Card expired
Bank blocked the transaction

Solutions:

Update your payment method in Settings → Billing
Contact your bank if the card should work
Try a different payment method
Contact billing@aegisrunner.com for assistance

Lost access after downgrade

Cause: Resources exceed new plan limits.

Solutions:

Delete projects to meet new limits
Remove team members if over limit
Upgrade back to previous plan
Data older than retention period is deleted

Integration Issues

API returns 401 Unauthorized

Possible Causes:

Invalid or missing API key
API key was revoked
Wrong authorization header format

Solutions:

Verify your API key in Settings → Security
Generate a new API key if needed
Use format: Authorization: Bearer YOUR_KEY
Ensure key hasn't been accidentally exposed and revoked

Slack notifications not working

Possible Causes:

Webhook URL is incorrect
Slack app was removed from workspace
Channel was deleted or renamed
Notifications are disabled

Solutions:

Test the webhook with "Send Test Message"
Create a new webhook if the old one doesn't work
Verify notification settings are enabled
Check Slack app is still installed

CI/CD pipeline fails to trigger tests

Possible Causes:

API key not set in CI secrets
Wrong suite ID
Rate limit exceeded
Plan doesn't include API access

Solutions:

Verify API key is properly configured in CI secrets
Double-check suite ID from AegisRunner
Add delays between requests if hitting rate limits
Upgrade to Pro or Business for API access

Performance Issues

Dashboard loads slowly

Solutions:

Check your internet connection
Clear browser cache
Try a different browser
If persistent, report to support

Test runs queued for long time

Cause: Queue backlog on lower tier plans.

Solutions:

Pro plans get priority queue
Business plans have no queue
Avoid peak hours for non-urgent runs
Upgrade for faster execution

Getting More Help

If your issue isn't listed above:

Check Documentation - Search our docs for related topics
Email Support - Contact support@aegisrunner.com
Include Details - Provide:
- Steps to reproduce
- Error messages
- Test run IDs
- Screenshots
- Browser and OS

Support Response Times

Plan	Response Time
Free	Best effort (3-5 business days)
Starter	Within 48 hours
Pro	Within 24 hours
Business	Within 4 hours (business hours)

Related Documentation

Debugging Tests - Deep dive into test failures
Crawl Results - Understanding crawl data
Test Data Management - Fix data issues

Troubleshooting

Articles

Common Issues

Need help?