Troubleshooting

This page covers common issues and their solutions when using the Azure Event Grid Simulator.

Certificate and HTTPS Issues

"The SSL connection could not be established"

Problem: Clients cannot connect to the simulator due to certificate issues.

Solutions:

1. Trust the development certificate:

   dotnet dev-certs https --trust

2. For self-signed certificates in code, disable certificate validation:

   {
     "dangerousAcceptAnyServerCertificateValidator": true
   }

3. For cURL, use the -k flag to skip certificate verification:

   curl -k -X POST "https://localhost:60101/api/events..."

Certificate not found on startup

Problem: The simulator fails to start with a certificate error.

Solution: Generate a development certificate:

dotnet dev-certs https --trust

For Docker deployments, export a certificate file:

dotnet dev-certs https --export-path ./azureEventGridSimulator.pfx --password YourPassword

Connection Issues

Events not being delivered to subscribers

Possible causes:

1. Subscriber is disabled - Check if the subscriber has "disabled": true

2. Topic is disabled - Check if the topic has "disabled": true

3. Filter not matching - Review filter configuration:

   {
     "filter": {
       "includedEventTypes": ["Order.Created"]
     }
   }

4. Subscription validation failed - Check logs for validation errors. For local development, set "disableValidation": true

5. Endpoint unreachable - Verify the endpoint URL is correct and accessible from where the simulator is running

"Connection refused" when delivering to localhost

Problem: The simulator cannot connect to a subscriber running on localhost.

Solutions:

1. For Docker: Use host.docker.internal instead of localhost:

   {
     "endpoint": "http://host.docker.internal:7071/api/MyFunction"
   }

2. Verify the subscriber is running on the expected port

3. Check firewall settings that may be blocking the connection

Configuration Issues

"No topics configured"

Problem: The simulator starts but shows no topics.

Solutions:

1. Verify appsettings.json exists in the working directory

2. Check for JSON syntax errors in the configuration file

3. Verify topic configuration is correct:

   {
     "topics": [
       {
         "name": "MyTopic",
         "port": 60101
       }
     ]
   }

"Topic name can only contain letters, numbers, and dashes"

Problem: Invalid topic or subscriber name.

Solution: Use only alphanumeric characters and dashes:

• Valid: my-topic-1, OrdersTopic, events-v2
• Invalid: my_topic, my.topic, my topic

Port already in use

Problem: The simulator fails to start because the port is in use.

Solutions:

1. Change the port in configuration
2. Stop the process using the port:

   # Find the process
   lsof -i :60101
   # or on Windows
   netstat -ano | findstr :60101

Authentication Issues

"401 Unauthorized"

Problem: Requests are rejected with a 401 error.

Solutions:

1. Verify the key matches - The aeg-sas-key header must match the topic's key value exactly

2. Check header name - Use aeg-sas-key (not aeg-sas-token for simple auth)

3. Disable authentication for testing - Set key to null:

   {
     "name": "MyTopic",
     "port": 60101,
     "key": null
   }

SAS token validation failing

Problem: Using aeg-sas-token but getting authentication errors.

Possible causes:

• Token has expired (check the e parameter)
• Resource URL doesn't match
• Signature is incorrect

Event Delivery Issues

Events stuck in pending state

Problem: Events are received but not delivered.

Check:

1. View the dashboard at https://localhost:<port>/dashboard
2. Check for retry delays - failed deliveries are retried with exponential backoff
3. Verify subscriber endpoint is responding

Events being dead-lettered

Problem: Events are going to dead-letter instead of being delivered.

Check the dead-letter files in the configured folder (default: ./dead-letters):

cat ./dead-letters/MyTopic/MySubscriber/*.json

The dead-letter file contains:

• deadLetterReason - Why the event was dead-lettered
• lastHttpStatusCode - The last HTTP status code received
• lastErrorMessage - The error message from the last attempt

Common reasons:

• HTTP 400, 401, 403, 413 responses cause immediate dead-lettering
• Max retry attempts exceeded
• Event TTL expired

Dashboard Issues

Dashboard not loading

Problem: Cannot access the dashboard UI.

Solutions:

1. Verify dashboard is enabled:

   {
     "dashboardEnabled": true
   }

2. Check the URL - Access at https://localhost:<port>/dashboard

3. Try a dedicated port:

   {
     "dashboardEnabled": true,
     "dashboardPort": 9000
   }

Logging and Debugging

Enable verbose logging

Add Serilog configuration to appsettings.json:

{
  "Serilog": {
    "MinimumLevel": {
      "Default": "Debug"
    },
    "WriteTo": [
      { "Name": "Console" }
    ]
  }
}

Check health endpoint

Verify the simulator is running:

curl -k https://localhost:60101/api/health
# Should return: OK

Getting Help

If you're still experiencing issues:

1. Check the GitHub Issues for known problems
2. Review the Architecture page to understand how the simulator works
3. Open a new issue with:
   • Your configuration (redact sensitive values)
   • Error messages from logs
   • Steps to reproduce the issue