theonedev/onedev · error · ExplicitException

Client ID needs to be specified to generate refresh token

Error message

Client ID needs to be specified to generate refresh token

What it means

GmailConnector's refresh-token generation callback reads the clientId field from the current connector edit form. If it is null, an ExplicitException is thrown because a Google OAuth client ID is mandatory to start the OAuth flow that produces a refresh token.

Source

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

	public void setSystemAddress(String systemAddress) {
		this.systemAddress = systemAddress;
	}
	
	@Editable(order=500, name="Check Incoming Email", description="Enable this to process issue or pull request comments posted via email")
	public InboxPollSetting getInboxPollSetting() {
		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

View on GitHub (pinned to d44925c47c)

Solutions

Fill in the Google Cloud OAuth 2.0 Client ID in the connector form before generating the refresh token.
Create OAuth credentials in Google Cloud Console (Gmail API enabled) if none exist yet.
Save/re-render the form so EditContext picks up the clientId value.

Example fix

// before: generate refresh token with clientId empty
clientId = null;
// after
clientId = "1234567890-abc.apps.googleusercontent.com";

Defensive patterns

Strategy: validation

Validate before calling

if (!clientId || clientId.trim() === "") throw new Error("Fill Client ID before generating refresh token");

Try / catch

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

Prevention

Create Google OAuth credentials before configuring the Gmail connector.
Fill clientId, clientSecret, and accountName together before clicking generate.
Check the form for empty required fields after pasting config from documentation.

When it happens

Trigger: Clicking the 'generate refresh token' action in the Gmail connector edit form while the 'Client ID' input is empty (EditContext input value is null).

Common situations: User tries to generate a refresh token before filling in OAuth credentials; form fields not yet saved; copy/paste of client secret but forgot client ID.

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/44e9dfd73ebb54b0. Report an issue: GitHub.