Skip to main content
Version: Next

Troubleshooting

Files Referenced in this Document

Table of Contents​

  1. Module Load Failure
  2. Database Connection Exception
  3. Migration Script Execution Error
  4. Dependency Injection Resolution Failure
  5. API Returns 404 or 500 Error
  6. Error Code Reference
  7. Debugging Tips and Preventive Measures

Module Load Failure​

Module load failure typically occurs during the plugin initialization phase, mainly due to incorrect module dependency configuration or incorrect database type configuration. In the CMSPluginEntry class, database module dependencies are dynamically added via the AddApplication method. If the database type configuration is incorrect, the corresponding module will fail to load.

Key code paths:

  • Database type judgment logic in CMSPluginEntry.Register method
  • Module dependencies defined by [DependsOn] attribute in CMSPluginModule

Common Causes:

  • Incorrect DatabaseType configuration value in appsettings.json (should be "mysql", "sqlserver", or "postgresql")
  • Missing corresponding database implementation project (e.g., MySQL, SqlServer, or PostgreSql project) in the solution
  • Broken module dependency chain, where a required dependency module is not correctly registered

Fix Steps:

  1. Check if the DatabaseType configuration in appsettings.json is correct
  2. Confirm that the project for the corresponding database type (e.g., CMS.Plugin.MyPluginName.MySQL) is included in the solution
  3. Verify if the [DependsOn] attribute in CMSPluginModule contains all necessary dependent modules

Section sources

Database Connection Exception​

Database connection exceptions typically manifest as connection timeouts, authentication failures, or database non-existence. Such issues are mainly related to connection string configuration and database service status.

Common Causes:

  • Incorrect connection string format in appsettings.json
  • Database service not started or network unreachable
  • Insufficient database user permissions
  • Database name does not exist

Fix Steps:

  1. Check if the connection string in CMS.Plugin.MyPluginName.EntityFrameworkCore/appsettings.json is correct
  2. Verify if the database service is running normally
  3. Confirm that the database user has sufficient permissions
  4. If the database does not exist, create the database first

Preventive Measures:

  • Use environment variables or external configuration centers to manage sensitive configurations
  • Use dedicated database accounts in production environments
  • Regularly back up database connection configurations

Section sources

Migration Script Execution Error​

Migration script execution errors typically occur during the database initialization phase at application startup. CMSPluginDbMigrationService is responsible for handling database migrations. If an issue occurs during migration, the application will fail to start normally.

Common Causes:

  • Migration project folder does not exist
  • EF Core tools not correctly installed
  • Database version conflict
  • Initial migration not created

Key Code Paths:

  • CMSPluginDbMigrationService.AddInitialMigrationIfNotExist method
  • CMSPluginDbMigrationService.MigrateDatabaseSchemaAsync method

Fix Steps:

  1. Confirm that the Migrations folder exists in the CMS.Plugin.MyPluginName.EntityFrameworkCore project
  2. Check if ABP CLI tools are installed
  3. If it is the first deployment, ensure there is an initial migration script
  4. Check specific error messages in logs to locate the root cause

Debugging Tips:

  • Enable detailed logging to view detailed output of the migration process
  • Manually execute abp create-migration-and-run-migrator command to test migration
  • Check if the solution directory structure meets expectations

Section sources

Dependency Injection Resolution Failure​

Dependency injection resolution failure typically manifests as service instantiation failure or constructor parameter resolution error. In this template, dependency injection configuration is mainly completed in CMSPluginEntry and various module classes.

Common Causes:

  • Service not correctly registered in IServiceCollection
  • Constructor parameter type does not match registered service type
  • Incorrect lifecycle configuration (e.g., injecting Scoped service into Singleton service)
  • Circular dependency

Key Code Paths:

  • Service registration in CMSPluginEntry.Register method
  • CMSPluginMyPluginNameExtensions.TryAddMyPluginName extension method

Fix Steps:

  1. Check if relevant services are correctly registered via context.Services
  2. Verify if service lifecycle configuration is reasonable
  3. Check if all constructor parameters can be correctly resolved
  4. Avoid complex initialization logic in constructors

Preventive Measures:

  • Use interfaces instead of concrete classes for dependency injection
  • Follow dependency injection best practices
  • Regularly review service registration code

Section sources

API Returns 404 or 500 Error​

API returning 404 or 500 errors are common runtime issues, typically related to route configuration, controller registration, or business logic exceptions.

Common Causes for 404 Error:

  • Controller not correctly registered
  • Route attribute configuration error
  • HTTP verb mismatch
  • API version mismatch

Common Causes for 500 Error:

  • Business logic exception not correctly handled
  • Database operation failure
  • External service call failure
  • Missing configuration

Key Code Paths:

  • [EnableApplicationPart] attribute on CMSPluginEntry class
  • Route configuration of controller classes
  • Exception handling in service layer

Fix Steps:

  1. Confirm controller class is correctly registered via [EnableApplicationPart]
  2. Check if route attributes (e.g., [Route], [HttpGet]) of the controller are correct
  3. View server logs to locate specific exception information
  4. Ensure all external dependencies (e.g., database, API) are accessible

Debugging Tips:

  • Use Postman or curl to test API endpoints
  • Enable detailed error messages (development environment only)
  • Add log recording at key locations

Section sources

Error Code Reference​

This template defines a standardized error code system to facilitate quick location and handling of exceptions. Error codes are mainly defined in the CMSPluginDomainErrorCodes class.

Diagram sources

Common Error Codes:

  • CMS.Plugin.MyPluginName:NameAlreadyExists: Indicates attempting to create an entity name that already exists
  • Other business-specific error codes can be defined in the CMSPluginDomainErrorCodes class

Usage Suggestions:

  • Use predefined error codes in business logic instead of hardcoded strings
  • Define clear error codes for each business exception
  • Include error codes in API responses to facilitate frontend handling

Section sources

Debugging Tips and Preventive Measures​

Debugging Tips​

Enable Detailed Logs:

  • Set log level to "Debug" or "Trace" in appsettings.json
  • Use structured logs to record key operations
  • Regularly review log files to discover potential issues

Check Module Dependency Order:

  • Ensure module order in [DependsOn] attribute is correct
  • Verify execution order of module initialization
  • Use debugger to trace module loading process

Verify Configuration File Format:

  • Use JSON validation tools to check appsettings.json format
  • Ensure all required configuration items are defined
  • Avoid using comments in configuration files (JSON standard does not support them)

Preventive Measures​

Code Level:

  • Follow modular design principles
  • Use dependency injection instead of direct instantiation
  • Implement comprehensive exception handling mechanisms

Configuration Level:

  • Store sensitive configurations in environment variables or secure configuration centers
  • Use configuration validation to ensure configuration correctness
  • Regularly back up important configurations

Deployment Level:

  • Perform complete integration testing before deployment
  • Use CI/CD pipelines to automate deployment process
  • Implement blue-green deployment or canary release strategies

Section sources

Last updated on