Troubleshooting

Common Issues

License Validation Fails

Symptom: All API endpoints return 403 Forbidden.

Possible causes:

1. Missing license file — ensure Licensing.LicenseFilePath or Licensing.LicenseFileBase64 is set
2. Wrong public key — the public key must match the key pair that signed the license
3. Expired license — check the ExpiresAt field in the license payload
4. Host mismatch — the request hostname must be in the license's AllowedHosts list (localhost is auto-allowed in dev)

Diagnosis: Check the Backoffice license page at Settings → License or call GET /api/admin/license directly.

Database Migration Errors

Symptom: dotnet ef database update fails.

Solutions:

# Ensure EF tools are installed
dotnet tool install --global dotnet-ef

# Run from the API project directory
cd HeadlessEcommerce.Api
dotnet ef database update --project ../HeadlessEcommerce.Infrastructure

If you encounter "relation already exists" errors, the migration may have been partially applied. Check the __EFMigrationsHistory table:

docker exec headless-ecommerce-db psql -U postgres -d HeadlessEcommerce \
  -c 'SELECT "MigrationId" FROM "__EFMigrationsHistory" ORDER BY "MigrationId"'

RabbitMQ Connection Refused

Symptom: Logs show RabbitMQ connection failed or outbox messages stay in Pending status.

Checklist:

1. Verify RabbitMQ is running: docker ps | grep rabbitmq
2. Check host/port in RabbitMQ config section
3. If using Docker Compose, ensure service name matches (rabbitmq not localhost)
4. Check RabbitMQ Management UI at http://localhost:15672

Media Files Not Loading

Symptom: Product images return 404.

Checklist:

1. Verify Storage.BaseUrl matches your public domain
2. Check the wwwroot/media directory exists and has correct permissions
3. In Docker, verify the api_media volume is mounted at /app/wwwroot/media
4. Check the Media table — PublicUrl should contain relative paths like product-images/filename.png

CORS Errors

Symptom: Browser console shows Access-Control-Allow-Origin errors.

Solution: Add your frontend domains to the allowed origins list:

AllowedCorsOrigins__0=https://store.yourdomain.com
AllowedCorsOrigins__1=https://admin.yourdomain.com

Port Conflicts

Symptom: API fails to start with "address already in use".

The default ports:

• API: 8080 (in Docker), 5000/5001 (local dotnet run)
• PostgreSQL: 5432
• RabbitMQ: 5672 (AMQP), 15672 (management)

Override the API port:

ASPNETCORE_URLS=http://+:9090

Data Seeder

The HeadlessEcommerce.DataSeeder project seeds sample fashion store data.

Running

cd HeadlessEcommerce.DataSeeder
dotnet run -- --yes   # --yes skips confirmation prompt

Configuration

Edit HeadlessEcommerce.DataSeeder/appsettings.json:

{
  "ConnectionStrings": {
    "DefaultConnection": "Host=localhost;Port=5432;Database=HeadlessEcommerce;..."
  },
  "GeminiApiKey": "",
  "MediaRootPath": ""
}

Key	Description
GeminiApiKey	Google Gemini API key for AI image generation (optional)
MediaRootPath	Override image save location (default: API project's wwwroot/media)

What Gets Seeded

• 3 brands, 6 master categories, 8 sales categories
• 12 products with ~28 color variants (~130 SKU-level variants)
• 2 warehouses with inventory (random 5-50 stock)
• Dual pricing (USD + TRY)
• Bilingual content (EN + TR)
• AI-generated product images (requires Gemini API key)

tip

Without a Gemini API key, the seeder still creates all data — it just skips image generation and creates placeholder media records.

Logs

Viewing Logs

Local development:

cd HeadlessEcommerce.Api
dotnet run
# Logs appear in console

Docker:

docker logs -f quark-api

Coolify: Logs are available in the Coolify dashboard under your resource → Logs tab.

Useful Log Filters

Adjust log levels in appsettings.json for debugging:

{
  "Logging": {
    "LogLevel": {
      "HeadlessEcommerce.Infrastructure.Services": "Debug",
      "Microsoft.EntityFrameworkCore.Database.Command": "Warning"
    }
  }
}

warning

Setting EF Core command logging to Information or Debug will output full SQL queries including parameter values, which may contain sensitive data.