How to Troubleshoot Errors in nopCommerce

nopCommerce is a powerful and popular open-source eCommerce platform built on ASP.NET Core. However, like any web application, you may occasionally encounter errors due to misconfiguration, plugin conflicts, performance bottlenecks, or missing dependencies. Knowing how to troubleshoot efficiently can save hours of frustration and help maintain a reliable online store.

This guide walks you through a practical and step-by-step approach to diagnose and fix common nopCommerce errors.

✅ Step 1. Enable Detailed Error Messages (Development Mode)

In production mode, nopCommerce hides detailed error messages for security. To debug issues locally:

1. Navigate to your installed folder.

2. Open appsettings.json.

3. Set the following configuration:

"Logging": {
  "LogLevel": {
    "Default": "Debug",
    "Microsoft": "Warning"
  }
},
"UseDetailedErrors": true

If you're hosting on IIS, also ensure ASPNETCORE_ENVIRONMENT is set to Development temporarily.

✅ Step 2. Check Error Logs from Admin Panel

nopCommerce has built-in logging.

1. Login to Admin panel.

2. Go to System → Log.

3. Review latest entries with Error or Fatal severity.

4. Check stack trace and error message details.

This is often enough to identify:

• Plugin failures

• SQL connection issues

• Missing configuration keys

✅ Step 3. Check Server Logs

If the error is not logged by nopCommerce, examine:

Server Type	Log Location
IIS on Windows	Event Viewer → Windows Logs → Application
Kestrel on Linux	Systemd logs (journalctl -fu kestrel-service)
SmarterASP shared hosting	Control Panel → Site Logs or Error Logs
Azure App Service	Log Stream / Application Logs

✅ Step 4. Enable File-Based Logging (Optional)

You can also enable file logging to track runtime errors:

1. Open appsettings.json.

2. Add file logging provider:

"Logging": {
  "LogLevel": { "Default": "Information" },
  "File": {
    "LogLevel": { "Default": "Warning" },
    "Path": "App_Data/Logs/log.txt"
  }
}

✅ Step 5. Troubleshoot Plugin Issues

Plugins are a common source of nopCommerce errors. If your site crashes after installing or updating a plugin:

1. Go to /Plugins folder.

2. Rename the plugin folder causing issues (e.g. Nop.Plugin.Abc → Nop.Plugin.Abc_disabled).

3. Restart application pool or redeploy.

4. Clear /wwwroot/bundles and /App_Data/TempFiles.

This disables the plugin and restores your store.

✅ Step 6. Fix Database Connection Issues

If you see:

"A network-related or instance-specific error occurred."

Then your SQL connection string might be wrong. Check App_Data/Settings.json:

{
  "DataConnectionString": "Server=SQL_SERVER;Database=nopCommerce;User Id=USER;Password=PASS;TrustServerCertificate=True;"
}

• Ensure SQL port 1433 is open.

• Test database connection with SQL Server Management Studio.

• For SmarterASP or Azure SQL — enable Allow Remote Connections.

✅ Step 7. Resolve Missing Dependencies

Errors like:

"Could not load type"
"Library not found"

Means dependencies are missing. Fix:

• Delete /bin and /obj folders.

• Run:

  dotnet restore
  dotnet build
  

• Deploy again.

✅ Step 8. Improve Performance & Timeouts

If your site is slow or times out:

Issue	Solution
Slow database queries	Enable SQL indexing / use SQL Profiler
Too many images	Enable image caching
Low hosting resources	Upgrade to VPS/Cloud
Background tasks slow	Disable unused scheduled tasks

✅ Step 9. Common Error Solutions

Error Message	Fix
Invalid anti-forgery token	Disable caching middleware or add <form> anti-forgery token
Access denied to folder	Grant write permissions to bin, App_Data, Plugins
404 on images	Run Admin → Maintenance → Clear Cache
Wrong .NET version	Use .NET SDK version supported by your nopCommerce version

✅ Step 10. Turn On Debug Mode (Temporary)

In appsettings.json, enable debug output:

"UseResponseCompression": false,
"HostingModel": "InProcess"

⚠️ Turn this off before going live.

🔧 Bonus: Tools for Troubleshooting nopCommerce

Tool	Use
Postman	Test API endpoints
SQL Server Profiler	Find slow DB queries
Application Insights	Live error monitoring
New Relic	Performance logs
MiniProfiler for .NET	Performance debugging

✅ When to Ask for Help

If you're still stuck, share:

• Error message

• nopCommerce version

• Hosting provider

• Last changes made

• Exception stack trace

Ask on Forums:

• https://www.nopcommerce.com/en/boards

• StackOverflow — tag nopcommerce

Final Thoughts

Troubleshooting nopCommerce becomes easy when approached systematically. Always:
✔️ Check logs
✔️ Reproduce issue
✔️ Disable plugins
✔️ Validate configuration
✔️ Monitor performance