Troubleshoot an L2J connection
Fix common L2J setup and delivery symptoms
Start with what you can see. GameServer logs identify connection and handler errors; Admin → Game Servers shows connection, version, and supported features.
Server stays Disconnected
Likely causes: ForgeportIntegration.start() never runs, Enabled=False, a
bad token, the JARs are missing at runtime, or outbound WSS is blocked.
Check: confirm both JARs are loaded, config/portal.properties is in the
GameServer working directory, and the host can reach wss.forgeport.net:443.
If the token was regenerated, download the configuration again.
Connector check fails
Likely causes: one registered provider throws, returns an invalid domain object, or queries the wrong schema.
Check: match the failed row in Admin to the registration listed in L2J features. Inspect the GameServer exception and test the SQL with the same database user.
Account linking fails
Likely causes: the integration uses the wrong password transform, queries the wrong account database, or treats a blocked account as a bad password.
Check: read the login server's actual verification code, then test one known account through both the game client and Forgeport. Never compare the stored hash as plain text.
Characters do not appear
Likely causes: the query filters the wrong account column, maps an invalid race/sex/class value, or returns invalid model fields.
Check: run the query with the linked normalized account and map every row to
GameCharacter. An account with no characters must return an empty list.
Catalog search returns nothing
Likely causes: .items(...) is missing, the stream is reused, or null
templates reach the mapper.
Check: return a fresh stream on every call and filter null entries. Search
for Adena and confirm item 57 exists in the pack's loaded data.
Purchase completes but the item does not arrive
Likely causes: the target is offline, the login hook is missing, the handler
validates the wrong player, or the mutation was executed outside
Delivery.apply(...).
Check: confirm .playerOnlineEvents() and the EnterWorld call are both
present. Then follow Give purchased items to characters and
test online and offline paths separately.
Delivery requires reconciliation
The connector cannot prove whether a game mutation completed after an exception or interrupted journal update. Do not replay it blindly. Check the character's inventory or entitlement first, then resolve the order in Admin → Reconciliation.