docs(deployment): document admin init crash on legacy internal_id mismatch (#16410)#16773
Open
YAMRAJ13y wants to merge 1 commit into
Open
docs(deployment): document admin init crash on legacy internal_id mismatch (#16410)#16773YAMRAJ13y wants to merge 1 commit into
YAMRAJ13y wants to merge 1 commit into
Conversation
…match (OpenCTI-Platform#16410) Add a Known issues entry to the upgrade guide for the 'User already exists' crash loop that occurs when a legacy admin account's internal_id does not match the hardcoded OPENCTI_ADMIN_UUID. Covers the symptom, cause, how to confirm, remediation guidance, and the APP__ADMIN__EXTERNALLY_MANAGED behavior. Closes OpenCTI-Platform#16410
Contributor
There was a problem hiding this comment.
Pull request overview
Adds operational upgrade guidance to the deployment docs by documenting a specific 7.x upgrade failure mode where legacy admin accounts can trigger a fatal FunctionalError: User already exists crash loop during admin initialization.
Changes:
- Adds a new Known issues section to the upgrade guide describing the legacy admin
internal_idmismatch scenario and the resulting crash loop. - Documents confirmation steps and remediation guidance (including avoiding the “change admin email” workaround).
- Notes
APP__ADMIN__EXTERNALLY_MANAGEDbehavior (adminaccount_statusforced toLockedon boot).
| FunctionalError: User already exists | ||
| ``` | ||
|
|
||
| **Cause** |
|
|
||
| This can affect any deployment carrying a sufficiently old admin account forward across the 7.x upgrade. | ||
|
|
||
| **How to confirm** |
|
|
||
| Look up the admin account by the email configured in `APP__ADMIN__EMAIL` and compare its stored `internal_id` with `OPENCTI_ADMIN_UUID` (`88ec0c6a-13ce-5e39-b486-354fe4a7084f`). If they differ, you are hitting this issue. | ||
|
|
||
| **Remediation** |
|
|
||
| **Cause** | ||
|
|
||
| On boot, the platform resolves the admin account by its hardcoded identifier `OPENCTI_ADMIN_UUID` (`88ec0c6a-13ce-5e39-b486-354fe4a7084f`). On deployments where the admin account was created before this identifier became deterministic, the stored admin document has a **random** `internal_id` that does not match `OPENCTI_ADMIN_UUID`. As a result the admin lookup returns nothing, initialization falls into the *create* path, and creating the account collides with the existing admin on `user_email` — which raises `User already exists` and aborts startup. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Proposed changes
Adds a Known issues section to the upgrade guide documenting the
User already existscrash loop that can occur when upgrading an older platform to 7.x, as requested in #16410.When a legacy admin account's stored
internal_iddoes not match the hardcodedOPENCTI_ADMIN_UUID(88ec0c6a-13ce-5e39-b486-354fe4a7084f),initAdmin()takes the create path, collides onuser_email, and aborts boot withFunctionalError: User already exists.The entry covers:
internal_id≠OPENCTI_ADMIN_UUID.internal_idagainst the constant.APP__ADMIN__EMAIL, which orphans the legacy admin.APP__ADMIN__EXTERNALLY_MANAGED— documents that it forces the adminaccount_statustoLockedon each boot.All claims verified against
opencti-platform/opencti-graphql/src/domain/user.js(initAdmin()at L2044,User already existsthrow at L733) andschema/general.js(OPENCTI_ADMIN_UUID).Related issues
Closes #16410
How to test
Review the rendered Deployment → Upgrade page: the new Known issues section appears with correctly formatted admonitions.