theonedev/onedev · error · ExplicitException

Invalid state. Please make sure you are visiting OneDev usin

Error message

Invalid state. Please make sure you are visiting OneDev using server url specified in system setting

What it means

OAuthCallbackPage validates the OAuth 'state' parameter against the 'oauthState' attribute stored in the Wicket session when the flow started. On mismatch it throws ExplicitException('Invalid state...') because the callback may be forged, replayed, or issued via a different server URL (session cookie not shared).

Source

Thrown at server-core/src/main/java/io/onedev/server/web/page/security/OAuthCallbackPage.java:32

public class OAuthCallbackPage extends SimplePage {

	public static final String MOUNT_PATH = "~oauth/callback";
	
	private static final String PARAM_CODE = "code";
	
	private static final String PARAM_STATE = "state";

	private String code;
	
	private String state;
	
	public OAuthCallbackPage(PageParameters params) {
		super(params);
		state = params.get(PARAM_STATE).toString();
		code = params.get(PARAM_CODE).toString();
		
		if (!state.equals(Session.get().getAttribute("oauthState"))) {
			throw new ExplicitException(_T("Invalid state. Please make sure you are visiting "
					+ "OneDev using server url specified in system setting"));
		} else {
			Session.get().setAttribute("oauthCode", code);
		}
	}

	@Override
	protected String getTitle() {
		return _T("Please wait...");
	}

	@Override
	protected String getSubTitle() {
		return null;
	}

	@Override
	public void renderHead(IHeaderResponse response) {

View on GitHub (pinned to d44925c47c)

Solutions

Set the server url in Admin > System Setting to the exact base URL users use, and make the OAuth provider's redirect/callback URL match it (same scheme and host).
Clear cookies / restart the browser session and retry the SSO login from scratch.
Check any reverse proxy forwards cookies and does not rewrite the Host header.
Ensure only one login flow is active; do not reuse an old callback URL directly.

Example fix

// before (provider app config)
redirect uri: http://localhost:6610/oauth2/callback
// after (match the server url users actually visit)
redirect uri: https://onedev.example.com/oauth2/callback

Defensive patterns

Strategy: retry

Validate before calling

String expected = (String) Session.get().getAttribute("oauthState");
boolean valid = expected != null && expected.equals(stateParam);

Try / catch

try {
  new OAuthCallbackPage(params);
} catch (ExplicitException e) {
  // restart SSO login from the login page
  setResponsePage(SignInPage.class);
}

Prevention

Align server url and OAuth provider redirect URL exactly (scheme+host).
Start and finish the OAuth flow in the same browser session.
Avoid keeping login tabs open for long periods.
Ensure proxies preserve cookies and the Host header.

When it happens

Trigger: The state query parameter in the OAuth provider's redirect does not equal the session's oauthState — the auth flow was started on a different host/URL than the callback URL configured in the OAuth provider, the session expired mid-flow, or the callback was opened in a different browser/session.

Common situations: Server url in system setting differs from the redirect URL registered with the SSO provider (http vs https, localhost vs domain), causing cookies/session mismatch; reverse proxy stripping cookies; user waiting too long between starting login and being redirected; double-opening the login flow.

Related errors

AI-assisted analysis of theonedev/onedev@d44925c47c (2026-09-06). Data as JSON: /api/errors/ac21cfc1f65a5905. Report an issue: GitHub.