ZITADEL: First instance admin cannot log in with username (email required but not documented clearly)

[axies20]

Describe the bug

When starting ZITADEL with ZITADEL_FIRSTINSTANCE_ORG_HUMAN_USERNAME, it is expected that the admin user can log in using the provided username.

However, the login UI requires an email (or login name), and using the username (e.g. admin) results in:

User could not be found

This is confusing because:

• the environment variable explicitly defines a username
• but the login flow does not accept it
• and there is no clear indication that email must be used instead

Additionally, if ZITADEL_FIRSTINSTANCE_ORG_HUMAN_EMAIL_ADDRESS is not set, the actual login identifier becomes unclear.

---

Regression

No response

---

Steps to reproduce

1. Run ZITADEL using Docker / Aspire with the following configuration:

builder.AddZitadel("zitadel");

2. Open the login page

3. Enter:

   • Login: admin
   • Password: Admin123!

4. Observe error:

   • User could not be found

5. Restart with:

.WithEnvironment("ZITADEL_FIRSTINSTANCE_ORG_HUMAN_EMAIL_ADDRESS", "admin@localhost")

6. Login using:

   • admin@localhost

7. Login succeeds

---

Expected behavior

One of the following should happen:

1. Username login should work if ZITADEL_FIRSTINSTANCE_ORG_HUMAN_USERNAME is set

OR

2. Documentation and/or UI should clearly indicate that:

   • login requires email/login name
   • username alone is not sufficient

Currently this behavior is not obvious and leads to confusion during initial setup.

---

Screenshots

No response

---

IDE and version

Rider

---

IDE version

No response

---

Nuget packages

CommunityToolkit.Aspire.Hosting.Zitadel

---

Additional context

No response

---

Help us help you

Yes, I'd like to be assigned to work on this item

[aaronpowell]

@dealloc any thoughts?

[dealloc]

Odd, I'm 100% certain the integration worked when I made a PR as it's lifted from code I used in internal projects.

I do know over the course of the PR the versions got updated a few times, I might've messed up there at some point?