theonedev/onedev · error · ExplicitException

Account name needs to be specified to generate refresh token

Error message

Account name needs to be specified to generate refresh token

What it means

GmailConnector's refresh-token callback additionally requires the Gmail account name (email address) being configured. Without it the resulting refresh token cannot be tied to the right account, so an ExplicitException is thrown.

Source

Thrown at server-plugin/server-plugin-mail-gmail/src/main/java/io/onedev/server/plugin/mail/gmail/GmailConnector.java:134

		return inboxPollSetting;
	}

	public void setInboxPollSetting(InboxPollSetting inboxPollSetting) {
		this.inboxPollSetting = inboxPollSetting;
	}

	@SuppressWarnings("unused")
	private static RefreshToken.Callback getRefreshTokenCallback() {
		String clientId = (String) EditContext.get().getInputValue("clientId");
		if (clientId == null)
			throw new ExplicitException("Client ID needs to be specified to generate refresh token");
		String clientSecret = (String) EditContext.get().getInputValue("clientSecret");
		if (clientSecret == null)
			throw new ExplicitException("Client secret needs to be specified to generate refresh token");

		String accountName = (String) EditContext.get().getInputValue("accountName");
		if (accountName == null)
			throw new ExplicitException("Account name needs to be specified to generate refresh token");

		Collection<String> scopes = Lists.newArrayList("https://mail.google.com/");

		return new RefreshToken.Callback() {

			@Override
			public String getAuthorizeEndpoint() {
				return AUTHORIZE_ENDPOINT;
			}

			@Override
			public Map<String, String> getAuthorizeParams() {
				Map<String, String> params = new HashMap<>();
				params.put("access_type", "offline");
				params.put("login_hint", accountName);
				params.put("prompt", "consent");
				return params;
			}

View on GitHub (pinned to d44925c47c)

Solutions

Fill in the Gmail account name (full email address of the mailbox to send from) before generating the refresh token.
Ensure the entered account matches the one you authorize in the Google consent screen.
Re-open the connector form and complete all required fields (clientId, clientSecret, accountName).

Example fix

// before
accountName = null;
// after
accountName = "notifications@example.com";

Defensive patterns

Strategy: validation

Validate before calling

if (!accountName || accountName.trim() === "") throw new Error("Fill Account Name before generating refresh token");

Try / catch

try {
    generateRefreshToken();
} catch (ExplicitException e) {
    alert("Complete the connector form first: " + e.getMessage());
}

Prevention

Enter the full Gmail address of the sending mailbox.
Ensure the authorized Google account matches the account name field.
Use a checklist: clientId, clientSecret, accountName before generating.

When it happens

Trigger: Generating a refresh token with clientId and clientSecret filled but the 'Account Name' input empty in the Gmail connector edit form.

Common situations: User fills OAuth credentials but forgets the mailbox address field; using a service account vs user mailbox confusion; field left blank on a cloned connector config.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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