FAQ

The most common questions beginners run into. If your issue is not covered here, check the module docs in the Documentation Index or the Changelog for version-specific behavior.

The admin entry is /admin/{AdminRouteSecret}. With the default configuration, visit:

http://localhost:port/admin/i4ByMAX4

That address sets a secret cookie and redirects to /Admin/. Use the port shown in the console startup log.

2. What is the default account? What if I forget the password?

The template default admin is admin / 123yyq. To reset a forgotten password, log in with another admin account, open System → User Management, click Edit on the target user, enter a new password, and save. If no admin account is available, you will need a developer to handle the database directly or restore from backup.

3. Opening /Admin returns 404?

You are missing the cookie set by AdminRouteSecret. Visit /admin/{AdminRouteSecret} (the URL with the secret) first instead of /Admin directly. If the secret was changed, use the new one.

4. Database connection fails / first startup errors?

Check the connection string in appsettings.json (or appsettings.Development.json)
Use Charset=utf8mb4 in the MySQL connection string
Confirm the database service is running, credentials are correct, and the target database exists
First run needs UseAutoSyncStructure(true) to create tables; for production, sync the schema on a development database first

5. Schema / new columns are not synced?

During development, UseAutoSyncStructure(true) syncs automatically; production usually sets it to false. If development is not syncing either, confirm the entity class is in an assembly registered in EasyAdminBlazorOptions.Assemblies and restart the project.

6. Chinese text is garbled?

Add Charset=utf8mb4 to the MySQL connection string; use utf8mb4 for the database and tables too
For page rendering, check <meta charset="utf-8" /> in App.razor

7. Chat / online status does not work?

The chat extension depends on Redis. Check that:

Program.cs calls AddEasyAdminBlazorChat() and app.UseChat()
Redis:ConnectionString is correct and the Redis server is running
Chat is intentionally disabled when Redis is not configured

8. File/image uploads fail after deployment?

Check write permission on wwwroot/uploads (grant it to the running account for IIS, Windows service, or Linux). Upload limits and image processing parameters are configured under FileSettings.

9. Blazor Server keeps disconnecting and reconnecting?

When accessed through a reverse proxy in production, you must forward the WebSocket Upgrade/Connection headers and increase proxy_read_timeout. See Deployment. Occasional disconnects in development are normal (e.g. recompilation, long idle).

10. Problems after changing AesKey or AdminRouteSecret?

AesKey encrypts cookies and other data; after changing it, all logged-in users must log in again, which is expected. After changing AdminRouteSecret, the admin entry becomes /admin/{your-new-secret}.

The captcha is provided by the EasyAdminBlazor.Captcha extension:

builder.AddEasyAdminBlazor(new EasyAdminBlazorOptions
{
    EnableLoginCaptcha = true,
    ...
})
    .AddEasyAdminBlazorCaptcha(options =>
    {
        options.Chars = "0123456789";
    });

Make sure the package is installed, EnableLoginCaptcha = true, and AddEasyAdminBlazorCaptcha is called.

12. Email sending fails?

The mail extension supports two channels:

SMTP: configure SmtpSettings (Server, Port, Username, Password, FromEmail, EnableSsl). Common causes: the mailbox provider requires an authorization code instead of the login password; port 587 needs SSL/TLS enabled
SendCloud: configure the SendCloud node (ApiUser, ApiKey, SenderEmail, SenderName). When configured, SendCloud takes priority

See Extensions for details.

13. My entity does not appear in the code generator?

The entity must satisfy these conditions:

Inherit EntityFull, implement IEntity<>, or carry a [Table] attribute
Be in an assembly registered in EasyAdminBlazorOptions.Assemblies

Recompile and restart for the scanner to pick it up.

14. UI language switching has no effect?

Set EnableLocalization = true in Program.cs and uncomment:

var option = app.Services.GetService<IOptions<RequestLocalizationOptions>>();
if (option != null)
{
    app.UseRequestLocalization(option.Value);
}

15. Buttons/menus missing or no permission?

Button-level permissions are controlled by the button configuration in Menu Management and the role assignment in Role Management. Grant the role the corresponding menu and button permissions, then refresh.

16. The template creates an older version?

The template package and the core package may not be in sync. After creating a project from the template, upgrade the NuGet packages to the latest versions — see the Upgrade Guide.

Go-Live Security Check

Before going live, at minimum confirm:

AdminRouteSecret, AesKey, and the default admin password have been changed
UseAutoSyncStructure is disabled
HTTPS is configured
The uploads directory is writable
The database is backed up

FAQ

1. The project is running — where is the admin login?