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.

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

The admin entry is /admin/{AdminRouteSecret}:

  • Projects created from the template: the secret is an 8-character code generated randomly on first startup; it is printed in the console log (and kept in .aspnet/admin-route-secret.txt, so it survives restarts).
  • Projects that wire up the framework themselves: use the AdminRouteSecret configured in AddEasyAdminBlazor (without it the admin route has no protection and /Admin/ is reachable directly).

Visiting 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 -- look it up in the startup log or in the AddEasyAdminBlazor configuration) 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 derives the Data Protection application name and participates in key isolation for cookies and login tickets; 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}.

Login tickets are also bound to the issuing tenant and carry a server-side lifetime (TicketLifetime, 7 days by default). After upgrading to v2.3.2, legacy v1 tickets are treated as signed-out, so one re-login is expected. For multi-tenant deployments, configure the Security:AllowedHosts whitelist as well to stop a spoofed Host header from resolving to another tenant.

11. Login captcha not shown / failed-login limit not working?

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.


17. Will online upgrades lose data or require signing in again?

No. Upgrades only replace application files — uploads, logs, keys, configuration and the database are never written or deleted. A failed step only rolls back that step and the app is started again, so users stay signed in (as long as AesKey stays the same and the Data Protection key directory is not replaced — the updater protects .aspnet/DataProtection-Keys and the configured DataProtectionKeyPath by default; the framework puts the keys in the content root's .aspnet/DataProtection-Keys). IIS in-process hosting does not support online upgrades and disables the capability automatically.

18. Why is the code generator missing in production?

The code generator is enabled in local development only. Production does not expose the generator entry, preventing accidental changes to production code or database schema.

Go-Live Security Check

Before going live, at minimum confirm:

  • The admin entry secret is confirmed (projects created from the template use a random code -- keep the address from the startup log; projects that wire up the framework themselves should use their own random value), 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