paascloud/paascloud-master · error · ValidateCodeException

请在请求头中携带deviceId参数

Error message

请在请求头中携带deviceId参数

What it means

RedisValidateCodeRepository.buildKey constructs the Redis key 'code:<type>:<deviceId>' from the request's deviceId header. Codes are stored per device; if the deviceId header is missing or blank, ValidateCodeException '请在请求头中携带deviceId参数' is thrown for any get/put/remove operation.

Solutions

1. Add a unique, stable 'deviceId' header to every validate-code request (generate and check)
2. Generate a UUID on the client at install/first-visit and persist it
3. Check gateways/nginx aren't filtering the custom header
4. For browser apps, note cookies/session won't help here — the header is required

Example fix

// before
fetch('/code/sms', { method: 'POST' });
// after
fetch('/code/sms', { method: 'POST', headers: { deviceId: getOrCreateDeviceId() } });

const deviceId = localStorage.deviceId || (localStorage.deviceId = crypto.randomUUID());
if (!deviceId) throw new Error('deviceId missing');

function hasDeviceId(headers) { return typeof headers.deviceId === 'string' && headers.deviceId.trim().length > 0; }

try { await requestSmsCode(); } catch (ValidateCodeException e) { if (e.getMessage().contains("deviceId")) { regenerateDeviceIdAndRetry(); } }

When it happens

Trigger: Calling the validate-code generate or check endpoints without an HTTP header named 'deviceId', or sending it empty — raised from buildKey invoked by key/value/remove.

Common situations: Native app or browser frontend forgot to attach the deviceId header; a gateway stripped custom headers; backend test (Postman/curl) omitted the header; after migrating from session-based storage the client wasn't updated.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• 设备id参数不能为空
• 验证码已过期
• 无法找到缓存的用户社交账号信息
• 验证码处理器不存在
• 验证码生成器不存在

AI-assisted analysis of paascloud/paascloud-master@781281a950 (2026-09-10). Data as JSON: /api/errors/6a781f2284cbc41d. Report an issue: GitHub.

Appendix: source

Thrown at paascloud-common/paascloud-security-core/src/main/java/com/paascloud/security/core/validate/code/impl/RedisValidateCodeRepository.java:90

		}
		return (ValidateCode) value;
	}

	/**
	 * Remove.
	 *
	 * @param request the request
	 * @param type    the type
	 */
	@Override
	public void remove(ServletWebRequest request, ValidateCodeType type) {
		redisTemplate.delete(buildKey(request, type));
	}

	private String buildKey(ServletWebRequest request, ValidateCodeType type) {
		String deviceId = request.getHeader("deviceId");
		if (StringUtils.isBlank(deviceId)) {
			throw new ValidateCodeException("请在请求头中携带deviceId参数");
		}
		return "code:" + type.toString().toLowerCase() + ":" + deviceId;
	}

}

View on GitHub (pinned to 781281a950)